Read Federated contribution

GET

/v1/object-types/hospitality.federated_contribution/objects/{id}

const url = 'https://api.aerandil.com/v1/object-types/hospitality.federated_contribution/objects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

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

Read an existing instance.

Metadata for one participant’s local contribution to a run. Stores hashes, bucketed counts, payload reference / hash, validation warnings, optional attestation reference. Does not store raw local records, raw guest text, direct identifiers, PAN, PHI, or clinical detail — those are rejected structurally by the contribution validators (proposal 0021 §4.7 / §7).

Authorizations

aerandil_oauth
objects:read
aerandil_oauth
objects:hospitality.federated_contribution:read

Parameters

Path Parameters

required

string format: uuid

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

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

200

Object found.

application/json

object

created_at

required

string format: date-time

required

string format: uuid

object_type

required

Allowed value: hospitality.federated_contribution

properties

required

object

accepted_at

Set by validation

string format: date-time

attestation_reference

TEE / runner attestation if used

string

clipping_applied

required

Required true for model updates (validator enforced)

boolean

contribution_fingerprint

required

SHA-256 over the contribution ledger payload. Same ledger key with a different fingerprint is rejected.

string

contribution_kind

required

Encrypted aggregate / noisy aggregate / model update / metrics only / attestation only

string

Allowed values: encrypted_aggregate noisy_aggregate model_update metrics_only attestation_only

contribution_slot

Slot discriminator when a definition declares multiple slots; null for the default single-slot path

string

delta_spent

Local DP spend

string format: decimal

epsilon_spent

Local DP spend

string format: decimal

required

Contribution id

string

input_snapshot_hash

required

Hash over local eligible input snapshot metadata; never raw data

string

input_window_end

required

Must match run

string format: date-time

input_window_start

required

Must match run

string format: date-time

local_code_digest

required

Must match approved definition unless reviewed override

string

local_record_count_bucket

required

Bucketed record count; exact counts stay local unless reviewed

string

Allowed values: lt_10 10_49 50_99 100_499 500_999 1000_plus

local_runner_version

required

Runner or agent version

string

local_subject_count_bucket

Required for person-affecting definitions

string

Allowed values: lt_10 10_49 50_99 100_499 500_999 1000_plus

minimum_local_runner_version_at_submission

Snapshot of the effective hard floor from the contribution's definition at action time

string

participation_id

required

Participation id

string

payload_hash

Required when payload_reference is set

string

payload_reference

Encrypted payload / clean-room output / secure aggregation share reference. Never the payload body itself.

string

payload_size_bytes

Safety bound

integer

recommended_local_runner_version_at_submission

Snapshot of the effective soft baseline from the contribution's definition at action time

string

rejection_reason

Bounded

string

run_id

required

Federated run id

string

secure_aggregation_mask_ref

Optional protocol metadata

string

status

required

Lifecycle status

string

Allowed values: requested local_prepared submitted accepted rejected suppressed withdrawn expired

submitted_at

Set by action

string format: date-time

validation_warnings

required

Local runner warnings (bounded text array)

Array<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

Example

{
  "object_type": "hospitality.federated_contribution",
  "properties": {
    "contribution_kind": "encrypted_aggregate",
    "local_record_count_bucket": "lt_10",
    "local_subject_count_bucket": "lt_10",
    "status": "requested"
  },
  "scope": {
    "level": "tenant"
  }
}

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

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