Search Recovery toolkit

POST

/v1/object-types/hospitality.recovery_toolkit/search

const url = 'https://api.aerandil.com/v1/object-types/hospitality.recovery_toolkit/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"branch":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","cursor":"example","filters":[{"property":"id","type":"eq","value":"example"}],"limit":1,"order":"asc","property_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","scope":{"level":"tenant"},"sort_by":"created_at"}'
};

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/object-types/hospitality.recovery_toolkit/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "cursor": "example", "filters": [ { "property": "id", "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.

The property’s comp-authority policy + recovery framework + top-cover principle. The policy_kind enum spans the observed-in-production patterns (Ritz flat_universal, USHG per_role_per_shift_cumulative, Aman training_and_tenure_based, the strict escalation_only); the role_authorities array carries per-role rules for the policies that need them (per-role-per-incident, per-role-mixed). The original sketch of ‘comp authority per role’ could not admit the universal, per-shift cumulative, training-based, or escalation-only shapes — the enum + array pair is the research-led correction. See products/forge/spec/proposals/0002-service-philosophy.md §3.3 and §10 open question 1 for reviewer context. Soft validators on over-limit recoveries warn but don’t block — over-limit recoveries are exactly the data the operator most needs and would otherwise hide (the literature is explicit that hard blocks produce ‘ghost recoveries’ where the front line works around the system).

Authorizations

aerandil_oauth
objects:read
aerandil_oauth
objects:hospitality.recovery_toolkit:read

Request Body^required

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

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 id policy_kind recovery_process_framework top_cover_principle_text

Responses

200

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

application/json

object

data

required

Array<object>

object

created_at

required

string format: date-time

required

string format: uuid

object_type

required

Allowed value: hospitality.recovery_toolkit

properties

required

object

comp_category_definitions

Property-specific comp categories

flat_universal_per_guest_per_day

Recovery toolkit flat universal per guest per day

Flat universal per-guest-per-day cap

object

amount

required

string format: decimal

currency

required

string format: iso-4217

flat_universal_per_incident_limit

Recovery toolkit flat universal per incident limit

Flat universal per-incident comp limit

object

amount

required

string format: decimal

currency

required

string format: iso-4217

required

Toolkit id

string

policy_kind

required

Comp authority policy kind

string

Allowed values: flat_universal per_role_per_incident per_role_per_shift_cumulative per_role_mixed training_and_tenure_based escalation_only

recovery_process_framework

required

Recovery process framework

string

Allowed values: ritz_three_steps ushg_5_as aman_unscripted custom

role_authorities

Recovery toolkit role authorities

Per-role comp authority rules

Array<object>

object

comp_categories_allowed

Array<string>

Allowed values: room_night food_beverage spa retail parking other

escalation_required_above

object

amount

required

string format: decimal

currency

required

string format: iso-4217

per_guest_per_day

object

amount

required

string format: decimal

currency

required

string format: iso-4217

per_incident_limit

object

amount

required

string format: decimal

currency

required

string format: iso-4217

per_shift_cumulative

object

amount

required

string format: decimal

currency

required

string format: iso-4217

role_code

required

string

top_cover_principle_text

required

Top-cover principle

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.recovery_toolkit",
      "properties": {
        "policy_kind": "flat_universal",
        "recovery_process_framework": "ritz_three_steps",
        "role_authorities": [
          {
            "comp_categories_allowed": [
              "room_night"
            ]
          }
        ]
      },
      "scope": {
        "level": "tenant"
      }
    }
  ]
}

422

Validation error — unknown property or filter type mismatch.

Search Recovery toolkit

Authorizations

Request Bodyrequired

Responses

200

Example

422

Request Body^required