Detect recurring failure pattern

POST

/v1/actions/hospitality.action.detect_recurring_failure_pattern/apply

curl --request POST \
  --url https://api.aerandil.com/v1/actions/hospitality.action.detect_recurring_failure_pattern/apply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "params": { "confidence": "low", "confidence_score": "example", "detection_window_end": "2026-04-15T12:00:00Z", "detection_window_start": "2026-04-15T12:00:00Z", "event_count": 1, "expires_at": "2026-04-15T12:00:00Z", "external_record_ref": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "factors_considered": [ "recovery_event_density" ], "failure_categories_observed": [ "staff_interaction" ], "failure_subject_themes": [ "example" ], "housekeeping_task_refs": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "message_triage_refs": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "pattern_context_snapshot": {}, "pattern_kind": "recurring_failure_category", "policy_outcomes": [ "gdpr_art22_explanation_required" ], "pre_shift_lineup_event_refs": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "rationale_text": "example", "recommended_remediation_action_ref": "example", "recommended_remediation_kind": "chain_typed_action", "recommended_remediation_params": {}, "recovery_event_refs": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "room_ref": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "root_cause_hypotheses": [ { "contribution": "example", "kind": "equipment_malfunction", "narrative_text": "example" } ], "run_id": "example", "service_philosophy_ref": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "severity_band": "low", "severity_score": "example", "subject_id": "example", "subject_kind": "failure_category_hotspot", "vendor_id": "example", "vendor_model_version": "example", "venue_ref": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "work_order_refs": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ] }, "return_modified": false, "target": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "object_type": "hospitality.property" } }'

• Production API

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.

Effects: 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.

Authorizations

• aerandil_oauth
  actions:apply
• aerandil_oauth
  actions:hospitality.action.detect_recurring_failure_pattern:apply

Request Body^required

Media typeapplication/json

object

branch

Apply against an open branch’s overlay view instead of the canonical (main) plane. The action’s writes land in the branch’s copy-on-first-write overlay, its events in the branch’s own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (POST /v1/branches forks one).

string format: uuid

params

required

object

confidence

required

Confidence ordinal

string

Allowed values: low medium high

confidence_score

Optional calibrated confidence score [0, 1]

string format: decimal

detection_window_end

required

Detection window end

string format: date-time

detection_window_start

required

Detection window start

string format: date-time

event_count

required

Clustered event count

integer

expires_at

Expiry

string format: date-time

external_record_ref

Optional vendor raw-payload reference

string format: uuid

factors_considered

required

Signals considered

Array<string>

Allowed values: 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

failure_categories_observed

required

Observed failure categories

Array<string>

Allowed values: 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

failure_subject_themes

required

Subject theme labels

Array<string>

housekeeping_task_refs

Optional clustered housekeeping tasks

Array<string>

message_triage_refs

Optional clustered message triages

Array<string>

pattern_context_snapshot

required

Frozen context snapshot

object

key

additional properties

any

pattern_kind

required

Detected pattern class

string

Allowed values: 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

policy_outcomes

required

Policy flags

Array<string>

Allowed values: 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

pre_shift_lineup_event_refs

Optional clustered pre-shift lineup events

Array<string>

rationale_text

required

Explanation

string

recommended_remediation_action_ref

API name of the host-orchestrated chained action

string

recommended_remediation_kind

required

Recommended remediation class

string

Allowed values: 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

recommended_remediation_params

Proposed remediation params

object

key

additional properties

any

recovery_event_refs

Optional clustered service recovery events

Array<string>

room_ref

Optional room anchor for room/floor patterns

string format: uuid

root_cause_hypotheses

required

Structured root-cause hypotheses

Array<object>

object

contribution

required

string format: decimal

kind

required

string

Allowed values: 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

narrative_text

required

string

run_id

Optional run UUID

string

service_philosophy_ref

Optional referenced service philosophy

string format: uuid

severity_band

required

Severity band

string

Allowed values: low medium high critical

severity_score

Optional calibrated severity score [0, 1]

string format: decimal

subject_id

required

Clustered subject id

string

subject_kind

required

Clustered subject kind

string

Allowed values: 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

vendor_id

required

Detector vendor identity

string

vendor_model_version

Detector model version

string

venue_ref

Optional venue anchor

string format: uuid

work_order_refs

Optional clustered work orders

Array<string>

return_modified

When true, the response carries modified_objects and modified_links projections — the engine reads the event log inside the same transaction so the projection observes the handler’s own writes.

boolean

target

required

object

id

required

string format: uuid

object_type

required

Allowed value: hospitality.property

Responses

200

Action applied. modified_objects and modified_links populated when return_modified: true was supplied.

Media typeapplication/json

ApplyActionResponse

Envelope returned by the Aerandil action engine. correlation_id ties every event emitted by this invocation; modified_objects and modified_links project the events the handler emitted (per the action’s declared effects); warnings carries any non-blocking soft-validator observations.

object

correlation_id

required

Per-invocation correlation id; matches events.correlation_id for every event this action appended.

string format: uuid

modified_links

required

Links established or removed by this invocation. Empty when the caller did not request return_modified.

Array<object>

object

from_id

required

string format: uuid

from_type

required

string

kind

required

Allowed values: linked

link_type

required

Allowed values: 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

required

string format: uuid

to_type

required

string

modified_objects

required

Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request return_modified.

Array<object>

object

id

required

string format: uuid

kind

required

Allowed values: created modified

object_type

required

Allowed values: hospitality.service_recovery_pattern hospitality.recovery_pattern_detection_run

warnings

Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.

Array<object>

object

message

required

Human-readable summary, suitable for logging or operator-UI surfacing.

string

object_type

required

Object type the warning was raised against.

string

property

Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.

string

rule

required

Stable kebab-case rule identifier (e.g. comp-authority-over-limit).

string

Example

{
  "modified_links": [
    {
      "kind": "linked",
      "link_type": "hospitality.link.pattern_part_of_run"
    }
  ],
  "modified_objects": [
    {
      "kind": "created",
      "object_type": "hospitality.service_recovery_pattern"
    }
  ]
}

409

Conflict — concurrent modification or unique constraint violation.

422

Validation error — parameter validation or business-rule violation.