Define fault type

POST

/v1/actions/hospitality.action.define_fault_type/apply

curl --request POST \
  --url https://api.aerandil.com/v1/actions/hospitality.action.define_fault_type/apply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "params": { "brand_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "category": "hvac", "code": "example", "description": "example", "element": "light", "property_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "severity": "cosmetic", "title": "example" }, "return_modified": false }'

• Production API

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.

Effects: create hospitality.fault_type; modify hospitality.fault_type; link hospitality.link.fault_type_at_brand; link hospitality.link.fault_type_at_property.

Authorizations

• aerandil_oauth
  actions:apply
• aerandil_oauth
  actions:hospitality.action.define_fault_type: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

brand_id

The brand's catalogue (exactly one of brand_id / property_id)

string format: uuid

category

The trade that mends it (defaults to the element's)

string

Allowed values: hvac plumbing electrical furniture fixtures networking audio_visual structural exterior safety other

code

required

The catalogue's code for it

string

description

Notes for whoever raises or mends it

string

element

The room element the fault is in

string

Allowed values: light air_conditioning curtain safe door television phone wardrobe shower mirror toilet pipework minibar electrical other

property_id

One house's catalogue (exactly one of brand_id / property_id)

string format: uuid

severity

required

The severity an order raised from it starts at

string

Allowed values: cosmetic minor major blocking safety

title

required

The title an order raised from it is given

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

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.fault_type_at_brand hospitality.link.fault_type_at_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.fault_type

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.fault_type_at_brand"
    }
  ],
  "modified_objects": [
    {
      "kind": "created",
      "object_type": "hospitality.fault_type"
    }
  ]
}

409

Conflict — concurrent modification or unique constraint violation.

422

Validation error — parameter validation or business-rule violation.