Housekeeping requests

POST

/v1/functions/hospitality.function.housekeeping_requests/invoke

curl --request POST \
  --url https://api.aerandil.com/v1/functions/hospitality.function.housekeeping_requests/invoke \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "params": { "business_date": "2026-04-15", "horizon": "shift" }, "target": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "object_type": "hospitality.property" } }'

• Production API

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.

Authorizations

• aerandil_oauth
  functions:invoke
• aerandil_oauth
  functions:hospitality.function.housekeeping_requests:invoke

Request Body^required

Media typeapplication/json

object

params

required

object

business_date

The day whose next day ends the queue (defaults to the house's hotel date)

string format: date

horizon

`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

string

Allowed values: shift all

target

required

object

id

required

string format: uuid

object_type

required

Allowed value: hospitality.property

Responses

200

Function invoked. The body carries the typed return_value shaped by the function’s declared return_type.

Media typeapplication/json

InvokeFunctionResponse

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).

object

correlation_id

required

Per-invocation correlation id; appears on log/trace records this function emitted.

string format: uuid

return_value

required

object

as_of

required

string format: date-time

property_id

required

string format: uuid

requests

required

Array<object>

object

area_id

string format: uuid

assignee_id

string format: uuid

block_reason

string

Allowed values: do_not_disturb guest_in_room access_refused maintenance_required other

business_date

string format: date

due_at

required

string format: date-time

group_id

string format: uuid

priority

required

string

Allowed values: low normal high urgent

requested_by

string

Allowed values: guest desk floor pms automation

room_id

string format: uuid

started_at

string format: date-time

status

required

string

Allowed values: pending in_progress blocked complete skipped

task_id

required

string format: uuid

task_type

required

string

Allowed values: stayover departure vacant_pickup deep_clean turndown inspection public_area_clean public_area_inspection minibar laundry

urgency

required

string

Allowed values: overdue soon scheduled

soon_minutes

required

integer

Example

{
  "return_value": {
    "requests": [
      {
        "block_reason": "do_not_disturb",
        "priority": "low",
        "requested_by": "guest",
        "status": "pending",
        "task_type": "stayover",
        "urgency": "overdue"
      }
    ]
  }
}

Headers

Cache-Control

string

Always no-store — function results are time-sensitive and never cacheable.

404

Function or target object not found.

422

Parameter validation or domain-rule violation.