Skip to content
aerandil.com
GitHub

Search Federated intelligence program

POST
/v1/object-types/hospitality.federated_intelligence_program/search
curl --request POST \
  --url https://api.aerandil.com/v1/object-types/hospitality.federated_intelligence_program/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.

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”

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: 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 api_name display_name description owner_scope owner_ref purpose status governance_tier default_min_tenants default_min_properties default_min_subjects default_max_contributor_share default_epsilon default_delta privacy_budget_period legal_basis_summary dpa_reference dpia_reference coordinator_kind coordinator_reference participant_benefit_policy downstream_use_policy effective_from effective_to created_by_principal approved_at minimum_local_runner_version recommended_local_runner_version

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.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
has_more
required
boolean
next_cursor

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

string
Example
{
  "data": [
    {
      "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"
      }
    }
  ]
}

422

Section titled “422”

Validation error — unknown property or filter type mismatch.