Skip to content
aerandil.com
GitHub

Read Federated intelligence program

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

Read an existing instance.

Durable governance envelope for a family of related cross-tenant analyses or model runs. Carries purpose, governance tier, allowed analysis kinds, default minimum cohort rules, default privacy mechanisms, budget periods, legal-basis / DPA / DPIA references, coordinator metadata, and the review_gate_policy driving proposal 0020 approval gates. Cross-tenant programs require DPA references and structural minimum cohort floors (proposal 0021 §4.1 / §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_intelligence_program
properties
required
object
allowed_analysis_kinds
required
Analytics first; learning requires review
Array<string>
Allowed values: federated_analytics federated_learning private_set_intersection clean_room_query benchmark_export
allowed_output_kinds
required
Benchmark reports, calibration curves, model artifacts, signal packages
Array<string>
Allowed values: benchmark_report calibration_curve aggregate_metric model_artifact signal_package governance_card
api_name
required
Stable slug; unique within owner scope
string
approved_at
Set only via approval action
string format: date-time
coordinator_kind
required
Coordinator: aerandil / tenant / consortium / third_party_clean_room
string
Allowed values: aerandil tenant consortium third_party_clean_room
coordinator_reference
Optional system or contract reference
string
created_by_principal
`Principal::stable_id()` of the proposer
string
default_delta
Required when default_epsilon set and mechanism needs delta
string format: decimal
default_epsilon
Program-level default for DP definitions; null when DP not applicable
string format: decimal
default_max_contributor_share
required
No participant may dominate output beyond this share (decimal in [0,1])
string format: decimal
default_min_properties
required
Hard minimum for cross-tenant outputs
integer
default_min_subjects
Required when output can be person-affecting
integer
default_min_tenants
required
Hard minimum for cross-tenant outputs (>= 3 for cross_tenant_network)
integer
default_privacy_mechanisms
required
Default privacy mechanisms applied per definition
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
description
Operator-facing summary. No marketing claims.
string
display_name
required
Human-readable name
string
downstream_use_policy
Allowed uses for outputs; machine-readable policy can follow later
string
dpa_reference
DPA / consortium-agreement reference. Required for cross-tenant programs unless reviewer waives.
string
dpia_reference
Required for high-risk or person-affecting programs
string
effective_from
Effective from
string format: date-time
effective_to
Effective to
string format: date-time
governance_tier
required
Governance tier — floor for cohort / privacy validators
string
Allowed values: internal_portfolio cross_tenant_network consortium_governed high_risk_review
id
required
Program id
string
legal_basis_summary
Bounded summary; full legal document via external ref
string
minimum_local_runner_version
Hard floor — contributions whose `local_runner_version` parses below this semver are rejected at action time (AWS Lambda deprecation floor)
string
owner_ref
Consortium or operator governance reference when owner is not a single tenant
string
owner_scope
required
Owner scope: tenant / consortium / aerandil_managed
string
Allowed values: tenant consortium aerandil_managed
participant_benefit_policy
What participating tenants receive in return
string
privacy_budget_period
required
Default period for budget accounting
string
Allowed values: run day month quarter year lifetime
purpose
required
Drives legal / review expectations
string
Allowed values: rate_recommendation_calibration fraud_signal_calibration service_recovery_benchmark agent_quality_benchmark payment_review_benchmark outlet_profitability_benchmark energy_water_waste_benchmark operations_research consortium_standardization reviewed_custom
recommended_local_runner_version
Soft baseline — contributions whose `local_runner_version` parses below this semver emit `contribution_runner_version_outdated_warns` (Stripe-style API-version upgrade signal)
string
review_gate_policy
required
Names which definitions and outputs require proposal 0020 approval gates (JSON; per-tier required-review map).
status
required
Lifecycle status
string
Allowed values: draft reviewing active paused deprecated retired
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_intelligence_program",
  "properties": {
    "allowed_analysis_kinds": [
      "federated_analytics"
    ],
    "allowed_output_kinds": [
      "benchmark_report"
    ],
    "coordinator_kind": "aerandil",
    "default_privacy_mechanisms": [
      "cohort_threshold"
    ],
    "governance_tier": "internal_portfolio",
    "owner_scope": "tenant",
    "privacy_budget_period": "run",
    "purpose": "rate_recommendation_calibration",
    "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).