Skip to content
aerandil.com
GitHub

Read Federated analysis definition

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

Read an existing instance.

Versioned, reviewed computation plan. Names input object types, input field allowlist, forbidden field classes, local feature contract, local code reference / digest, local execution requirements, algorithm family, aggregation method, contribution bounds, privacy mechanisms, epsilon / delta per run, cohort policy, output schema, and required model-card / datasheet / threat-model / DPIA references. Immutable once approved (proposal 0021 §4.2 / §7).

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.federated_analysis_definition
properties
required
object
aggregation_method
required
Aggregation method
string
Allowed values: plain_aggregate_reviewed secure_sum noisy_count noisy_sum noisy_mean noisy_histogram noisy_quantile trimmed_mean weighted_average fedavg external_clean_room reviewed_custom
algorithm_family
required
Algorithm family
string
Allowed values: secure_sum count_rate histogram quantile calibration_curve outcome_decay fedavg fedxgb reviewed_custom
analysis_kind
required
Analytics / learning / PSI / clean-room / benchmark-export
string
Allowed values: federated_analytics federated_learning private_set_intersection clean_room_query benchmark_export
approved_at
Set by approval action
string format: date-time
approved_by_principal
Set by approval action
string
ci_width_warn_threshold
Maximum acceptable confidence-interval width (upper − lower) for this definition's outputs; wider intervals warn `output-confidence-interval-too-wide`. Per-definition because CI widths are unitless across queries.
string format: decimal
cohort_policy
required
Minimums and suppression rules; may inherit from program (JSON)
composition_group
Groups related definitions for privacy-budget composition
string
contribution_bounds
required
Min / max values, clipping norms, per-participant caps (JSON; required for every approved definition)
datasheet_template_ref
Required for benchmark exports and model artifacts
string
definition_api_name
required
Stable slug within program
string
delta_per_run
Required for approximate DP mechanisms
string format: decimal
dpia_reference
Required when program or definition is high-risk
string
epsilon_per_run
Required if DP applies
string format: decimal
forbidden_field_classes
required
Defaults include direct_identifier, free_text, payment_secret, etc.
Array<string>
id
required
Definition id
string
input_field_allowlist
required
Fully qualified field paths or named derived features
Array<string>
input_object_types
required
Aerandil object types eligible for local reads
Array<string>
local_code_digest
Required when local_code_reference is set; immutable once approved
string
local_code_reference
Optional code package / container / runner ref
string
local_execution_requirements
required
Runner version, memory / timeout bounds, offline mode, network egress policy (JSON; validator-enforced shape)
local_feature_contract
required
Bounded schema for local features and aggregate vectors (JSON; typed per-field shape enforced by validators in commit 5)
metric_warn_thresholds
Per-metric minimum acceptable validation values (JSON map metric name → number); outputs whose metric_values fall below warn `output-degraded-metrics`.
minimum_local_runner_version
Effective hard floor (max of program + definition pins, frozen at definition publish time)
string
model_card_template_ref
Required for model artifacts
string
objective
required
What question the run answers
string
output_review_required
required
True by default for cross-tenant and model outputs
boolean
output_schema
required
Bounded output shape; no dynamic arbitrary tables in v1 (JSON)
privacy_mechanisms
required
Privacy mechanisms applied — at least cohort_threshold for every cross-tenant output
Array<string>
Allowed values: cohort_threshold contribution_bounding differential_privacy secure_aggregation secure_multiparty_computation homomorphic_encryption private_set_intersection trusted_execution_environment manual_statistical_disclosure_control none_internal_portfolio_only
program_api_name
required
Stable reference to the program
string
recommended_local_runner_version
Effective soft baseline (max of program + definition pins, frozen at definition publish time)
string
review_notes
Bounded rationale for approval
string
status
required
Lifecycle status
string
Allowed values: draft reviewing approved deprecated revoked
threat_model_ref
Required for cross-tenant programs
string
version
required
Semver-like; immutable once approved
string
weighting_method
required
How contributions are weighted in aggregation
string
Allowed values: unweighted room_nights available_rooms eligible_events revenue reviewed_custom
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.federated_analysis_definition",
  "properties": {
    "aggregation_method": "plain_aggregate_reviewed",
    "algorithm_family": "secure_sum",
    "analysis_kind": "federated_analytics",
    "privacy_mechanisms": [
      "cohort_threshold"
    ],
    "status": "draft",
    "weighting_method": "unweighted"
  },
  "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).