Start federated run

POST

/v1/actions/hospitality.action.start_federated_run/apply

curl --request POST \
  --url https://api.aerandil.com/v1/actions/hospitality.action.start_federated_run/apply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "params": { "aggregation_protocol": "plain_aggregate_reviewed", "clean_room_job_ref": "example", "cohort_id": "example", "deadline_at": "2026-04-15T12:00:00Z", "initiating_workflow_run_id": "example", "input_window_end": "2026-04-15T12:00:00Z", "input_window_start": "2026-04-15T12:00:00Z", "privacy_budget_account_id": "example", "run_key": "example", "secure_aggregation_session_ref": "example", "trigger_kind": "scheduled" }, "return_modified": false, "target": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "object_type": "hospitality.federated_analysis_definition" } }'

• Production API

Start a run for an approved definition and cohort. Freezes the definition version and cohort snapshot, resolves eligible active participants, validates thresholds before collection, reserves privacy budget, and creates the run with status collecting. Idempotent on run_key. Validators (commit 5): run_definition_must_be_approved, run_cohort_must_be_approved, run_input_window_end_le_now_unless_forecast, run_minimum_participants_before_collection, run_privacy_budget_reservation_must_succeed.

Effects: create hospitality.federated_run; create hospitality.privacy_budget_event; modify hospitality.privacy_budget_account; link hospitality.link.federated_run_uses_definition; link hospitality.link.federated_run_uses_cohort; link hospitality.link.federated_run_started_by_workflow; link hospitality.link.federated_run_reserved_from_account.

Authorizations

• aerandil_oauth
  actions:apply
• aerandil_oauth
  actions:hospitality.action.start_federated_run:apply

Request Body^required

Media typeapplication/json

object

branch

Apply against an open branch’s overlay view instead of the canonical (main) plane. The action’s writes land in the branch’s copy-on-first-write overlay, its events in the branch’s own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (POST /v1/branches forks one).

string format: uuid

params

required

object

aggregation_protocol

required

Aggregation protocol

string

Allowed values: plain_aggregate_reviewed secure_aggregation clean_room_dp external_protocol

clean_room_job_ref

Required for third-party clean room

string

cohort_id

required

Approved cohort id

string

deadline_at

Contribution deadline

string format: date-time

initiating_workflow_run_id

Set when a proposal 0020 workflow started this run

string

input_window_end

required

Input window end

string format: date-time

input_window_start

required

Input window start

string format: date-time

privacy_budget_account_id

Privacy budget account to reserve from. Required when the definition's mechanism_family is a DP variant; the handler dispatches reserve_privacy_budget against this account keyed on the run's correlation_id (idempotent, atomic). Resolves to the (program, composition_group) account in practice; explicit reference avoids the multi-account ambiguity at the action boundary.

string

run_key

Optional caller-supplied idempotency key; otherwise derived

string

secure_aggregation_session_ref

Required for secure aggregation

string

trigger_kind

required

Scheduled / manual / workflow / agent / backfill

string

Allowed values: scheduled manual workflow agent_request backfill

return_modified

When true, the response carries modified_objects and modified_links projections — the engine reads the event log inside the same transaction so the projection observes the handler’s own writes.

boolean

target

required

object

id

required

string format: uuid

object_type

required

Allowed value: hospitality.federated_analysis_definition

Responses

200

Action applied. modified_objects and modified_links populated when return_modified: true was supplied.

Media typeapplication/json

ApplyActionResponse

Envelope returned by the Aerandil action engine. correlation_id ties every event emitted by this invocation; modified_objects and modified_links project the events the handler emitted (per the action’s declared effects); warnings carries any non-blocking soft-validator observations.

object

correlation_id

required

Per-invocation correlation id; matches events.correlation_id for every event this action appended.

string format: uuid

modified_links

required

Links established or removed by this invocation. Empty when the caller did not request return_modified.

Array<object>

object

from_id

required

string format: uuid

from_type

required

string

kind

required

Allowed values: linked

link_type

required

Allowed values: hospitality.link.federated_run_uses_definition hospitality.link.federated_run_uses_cohort hospitality.link.federated_run_started_by_workflow hospitality.link.federated_run_reserved_from_account

to_id

required

string format: uuid

to_type

required

string

modified_objects

required

Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request return_modified.

Array<object>

object

id

required

string format: uuid

kind

required

Allowed values: created modified

object_type

required

Allowed values: hospitality.federated_run hospitality.privacy_budget_event hospitality.privacy_budget_account

warnings

Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.

Array<object>

object

message

required

Human-readable summary, suitable for logging or operator-UI surfacing.

string

object_type

required

Object type the warning was raised against.

string

property

Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.

string

rule

required

Stable kebab-case rule identifier (e.g. comp-authority-over-limit).

string

Example

{
  "modified_links": [
    {
      "kind": "linked",
      "link_type": "hospitality.link.federated_run_uses_definition"
    }
  ],
  "modified_objects": [
    {
      "kind": "created",
      "object_type": "hospitality.federated_run"
    }
  ]
}

409

Conflict — concurrent modification or unique constraint violation.

422

Validation error — parameter validation or business-rule violation.