Skip to content
aerandil.com
GitHub

Read Automation

GET
/v1/object-types/hospitality.automation/objects/{id}
curl --request GET \
  --url https://api.aerandil.com/v1/object-types/hospitality.automation/objects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

Read an existing instance.

A declarative monitor→effect rule: when a condition is met — an object entering/leaving/changing within a filtered object set, a periodic sweep, or a cron schedule — the automation fires an effect (apply a registered action, call a read-only function, or send a notification). The effect never mutates state directly; apply_action fires the target action through the normal scope-checked action surface, and the requires_approval variant routes it through a 0020 approval_gate instead of applying. Only active automations fire. Mirrors Palantir AIP Automate; see products/labs/docs/palantir-aip-deep-scan.md §4.1.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Object id (UUID v7, server-generated at create time).

Query Parameters

Section titled “Query Parameters”
branch
string format: uuid

Read through an open branch’s copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with as_of (422). The branch must exist under the caller’s tenant.

Responses

Section titled “Responses”

200

Section titled “200”

Object found.

Media typeapplication/json
object
created_at
required
string format: date-time
id
required
string format: uuid
object_type
required
Allowed value: hospitality.automation
properties
required
object
approval_policy_ref
The approval policy the staged gate is opened under (proposal 0020)
string
condition_kind
required
The trigger-predicate class
string
Allowed values: object_set_added object_set_removed object_set_modified object_set_all time_cron event_named
created_by
required
Principal::stable_id() of the operator/agent that defined it — the audit anchor
string
cron_expression
The schedule (5-field cron, evaluated in UTC by the host-side schedule worker): required for `time_cron` and for the `object_set_all` sweep (`automation_condition_coherent`); meaningless for the tail-driven kinds
string
description_text
What this automation is for — the operator's own note
string
display_name
required
Human-readable name, surfaced in the operator console
string
effect_action
For `apply_action`: the registered action to fire (ApiName form); validated against the registry and forbidden from targeting an internal-only action (`automation_effect_coherent`, `automation_no_internal_effect_action`)
string
effect_function
For `call_function`: the read-only registry function to invoke (ApiName form)
string
effect_kind
required
The effect fired when the condition is met
string
Allowed values: apply_action call_function send_notification
effect_notification_template
For `send_notification`: the templated notification body/target (JSON)
effect_params_template
Template mapping triggering-object fields → the effect's input params (JSON; `${object.<prop>}` / `${previous.<prop>}` placeholders resolved per-firing by the evaluator)
event_type_ref
For `event_named`: the named domain event the condition watches (ApiName form, e.g. `room_queue.room_ready`). The event's payload is the image `object_set_filter` matches and `${event.<field>}` reads; required for `event_named` and forbidden for every other kind (`automation_condition_coherent`)
string
execution_mode
required
Per-object vs batch effect firing for object-set conditions
string
Allowed values: per_object batch
id
required
Automation id
string
max_cascade_depth
required
Loop guard: the maximum trigger-chain depth an effect firing may reach before the evaluator suppresses it (default 3). An automation whose effect trips another automation increments the depth along the `correlation_id` lineage
integer
modified_property_watch
For `object_set_modified`: the property api-names whose change trips the condition (JSON array); empty/absent = any property change. An entry `name:decreased` / `name:increased` trips only when that number moved that way (an absent side reads as zero)
object_set_filter
The search-filter predicate that defines the watched object set over `object_type_ref` (same filter grammar as object search); absent = every object of the type
object_type_ref
The object type the object-set condition watches (ApiName form); required for `object_set_*` kinds, absent for `time_cron` (`automation_condition_coherent`)
string
requires_approval
required
When true, the effect opens a 0020 approval_gate instead of applying (the human-approval-staging variant); requires `approval_policy_ref` (`automation_approval_requires_policy`)
boolean
status
required
Enablement lifecycle; only `active` automations fire
string
Allowed values: draft active paused archived
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
Example
{
  "object_type": "hospitality.automation",
  "properties": {
    "condition_kind": "object_set_added",
    "effect_kind": "apply_action",
    "execution_mode": "per_object",
    "status": "draft"
  },
  "scope": {
    "level": "tenant"
  }
}

Headers

Section titled “Headers”
ETag
string
/^"\d+"$/

Quoted strong validator (RFC 7232 §2.3) carrying the object’s monotonic version. Informational on the read path — object mutation goes through typed actions on /v1/actions/{action}/apply, not raw CRUD.

404

Section titled “404”

No object with that id (or soft-deleted).