Skip to content
aerandil.com
GitHub

Search Fault type

POST
/v1/object-types/hospitality.fault_type/search
curl --request POST \
  --url https://api.aerandil.com/v1/object-types/hospitality.fault_type/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "cursor": "example", "filters": [ { "property": "code", "type": "eq", "value": "example" } ], "limit": 1, "order": "asc", "property_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "scope": { "level": "tenant" }, "sort_by": "created_at" }'

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.

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

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
branch

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.

string format: uuid
cursor

Opaque cursor from a prior response’s next_cursor. Pass back verbatim; do not introspect.

string
filters

Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by limit.

Array
One of:
object
property
required
Allowed value: code
type
required
Allowed value: eq
value
required
string
limit

Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).

integer
>= 1 <= 500
order

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

string
default: asc
Allowed values: asc desc
property_id

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.

string format: uuid
scope
One of: discriminator: level
object
level
required
string
Allowed value: tenant
Allowed values: tenant
sort_by

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

string
default: created_at
Allowed values: created_at updated_at code title element category severity description status defined_at retired_at retire_reason

Responses

Section titled “Responses”

200

Section titled “200”

Search results, ordered by (sort_by, id) in the requested order (ascending by default).

Media typeapplication/json
object
data
required
Array<object>
object
created_at
required
string format: date-time
id
required
string format: uuid
object_type
required
Allowed value: hospitality.fault_type
properties
required
object
category
required
The work-order category an order raised from it starts with — the trade that mends it
string
Allowed values: hvac plumbing electrical furniture fixtures networking audio_visual structural exterior safety other
code
required
The catalogue's code for it — unique within the catalogue
string
defined_at
required
When it was first put in the catalogue
string format: date-time
description
Notes for whoever raises or mends it
string
element
The room element the fault is in (hubOS's icon), when it is in one
string
Allowed values: light air_conditioning curtain safe door television phone wardrobe shower mirror toilet pipework minibar electrical other
retire_reason
Why it was retired
string
retired_at
When it was retired
string format: date-time
severity
required
The severity an order raised from it starts at
string
Allowed values: cosmetic minor major blocking safety
status
required
active, or retired (final)
string
Allowed values: active retired
title
required
The title an order raised from it is given
string
provenance

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.

object
pins
object
key
additional properties
object
pinned_at
string format: date-time
pinned_by
object
reason
required
string
properties
object
key
additional properties
object
external_id
string
recorded_at
required
string format: date-time
source
required
string
source_updated_at
string format: date-time
stream
string
scope
required
One of: discriminator: level
object
level
required
string
Allowed value: tenant
Allowed values: tenant
tenant_id
required
string format: uuid
updated_at
required
string format: date-time
version
required
integer
>= 1
has_more
required
boolean
next_cursor

Cursor for the next page; omitted when the result set is exhausted.

string
Example
{
  "data": [
    {
      "object_type": "hospitality.fault_type",
      "properties": {
        "category": "hvac",
        "element": "light",
        "severity": "cosmetic",
        "status": "active"
      },
      "scope": {
        "level": "tenant"
      }
    }
  ]
}

422

Section titled “422”

Validation error — unknown property or filter type mismatch.