Create work order

POST

/v1/actions/hospitality.action.create_work_order/apply

const url = 'https://api.aerandil.com/v1/actions/hospitality.action.create_work_order/apply';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"branch":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","params":{"allow_duplicate":true,"asset_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","category":"hvac","description":"example","element":"light","fault_type_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","from_triage_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","out_of_order_end":"2026-04-15","out_of_order_start":"2026-04-15","return_status":"dirty","severity":"cosmetic","staff_member_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","stay_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","title":"example"},"return_modified":false,"target":{"id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","object_type":"hospitality.room"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.aerandil.com/v1/actions/hospitality.action.create_work_order/apply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "params": { "allow_duplicate": true, "asset_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "category": "hvac", "description": "example", "element": "light", "fault_type_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "from_triage_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "out_of_order_end": "2026-04-15", "out_of_order_start": "2026-04-15", "return_status": "dirty", "severity": "cosmetic", "staff_member_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "stay_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "title": "example" }, "return_modified": false, "target": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "object_type": "hospitality.room" } }'

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.

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

Authorizations

aerandil_oauth
actions:apply
aerandil_oauth
actions:hospitality.action.create_work_order:apply

Request Body^required

application/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

allow_duplicate

Raise it even when an order with the same title or fault type is already open on the room

boolean

asset_id

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

string format: uuid

category

Category (defaults to the fault type's, else the element's trade)

string

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

description

Description

string

element

The room element the fault is in (defaults to the fault type's)

string

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

fault_type_id

The catalogue entry the fault is — the house's or its brand's, active; fills what the call does not state

string format: uuid

from_triage_id

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

string format: uuid

out_of_order_end

Last out-of-order night (inclusive through-date; the night audit returns the room when it closes)

string format: date

out_of_order_start

First night the room is out of order (with out_of_order_end and return_status, or not at all)

string format: date

return_status

Housekeeping status the room re-enters on release

string

Allowed values: dirty pickup clean inspected

severity

Severity (defaults to the fault type's)

string

Allowed values: cosmetic minor major blocking safety

staff_member_id

Engineer to assign on creation

string format: uuid

stay_id

The guest stay that reported the fault; the order then reads reported_by_guest without carrying the guest

string format: uuid

title

Title (defaults to the fault type's, else the element's name)

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

required

string format: uuid

object_type

required

Allowed value: hospitality.room

Responses

200

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

application/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.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

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

required

string format: uuid

kind

required

Allowed values: created modified

object_type

required

Allowed values: hospitality.work_order hospitality.room_status_block hospitality.availability_day

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

409

Conflict — concurrent modification or unique constraint violation.

422

Validation error — parameter validation or business-rule violation.

Create work order

Authorizations

Request Bodyrequired

Responses

200

Example

409

422

Request Body^required