Federations API

Endpoints for managing cross-organization federations, membership, shared models, privacy budgets, and federated analytics.

Create a federation

POST /api/v1/federations

Creates a new federation for cross-organization collaborative model training.

Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Federation name (1-128 characters)
org_id	string	Yes	Owning organization identifier
description	string	No	Human-readable description (max 512 chars)

---

List federations

GET /api/v1/federations

Returns all federations. Optionally filter by org_id or name query parameters.

---

Retrieve a federation

GET /api/v1/federations/{federation_id}

---

Join a federation

POST /api/v1/federations/{federation_id}/join

Joins an organization to a federation. Body requires org_id.

---

Invite members

POST /api/v1/federations/{federation_id}/invite

Sends invitations to organizations. Body requires org_ids (string array).

---

List members

GET /api/v1/federations/{federation_id}/members

Returns all members with contribution statistics (rounds_contributed, total_samples, avg_accuracy, avg_loss, last_contribution_at).

---

Share a model

POST /api/v1/federations/{federation_id}/models

Shares a model with the federation. Body requires model_id. Only the federation owner can share models.

---

List shared models

GET /api/v1/federations/{federation_id}/models

Returns all models shared with the federation.

---

Get privacy budget

GET /api/v1/federations/{federation_id}/privacy

Returns the current differential privacy budget status.

Response

{
  "federation_id": "fed_abc123",
  "total_epsilon_budget": 10.0,
  "total_delta_budget": 1e-5,
  "current_epsilon_spent": 3.2,
  "epsilon_remaining": 6.8,
  "is_exhausted": false,
  "rounds_tracked": 15
}

---

Set privacy budget

PUT /api/v1/federations/{federation_id}/privacy/budget

Set or update the total differential privacy budget. Body requires total_epsilon_budget (float > 0). Optional total_delta_budget (default 1e-5).

---

Estimate privacy cost

GET /api/v1/federations/{federation_id}/privacy/estimate

Estimate the epsilon cost of a proposed training round without recording it.

Query Parameters

Parameter	Type	Required	Description
noise_multiplier	float	Yes	Noise multiplier (> 0)
sample_rate	float	Yes	Sample rate (between 0 and 1)
num_steps	int	No	Number of steps (minimum 1, default 1)
target_delta	float	No	Target delta

Response

{
  "current_epsilon": 3.2,
  "projected_epsilon": 3.85,
  "round_epsilon_cost": 0.65,
  "would_exceed_budget": false,
  "budget_epsilon": 10.0
}

---

Privacy history

GET /api/v1/federations/{federation_id}/privacy/history

Returns per-round differential privacy parameter history showing epsilon accumulation.

---

Descriptive statistics

POST /api/v1/federations/{federation_id}/analytics/descriptive

Run descriptive statistics (mean, std, percentiles) across groups.

Body Parameters

Parameter	Type	Required	Description
variable	string	Yes	Variable to compute statistics for
group_by	string	No	device_group or federation_member (default: device_group)
group_ids	string[]	No	Subset of group IDs
include_percentiles	boolean	No	Include 25th/50th/75th (default: true)
filters	object	No	Time range and platform filters

---

T-test

POST /api/v1/federations/{federation_id}/analytics/t-test

Run a two-sample t-test between two groups.

Body Parameters

Parameter	Type	Required	Description
variable	string	Yes	Variable to test
group_a	string	Yes	First group ID
group_b	string	Yes	Second group ID
confidence_level	float	No	Default 0.95

---

ANOVA

POST /api/v1/federations/{federation_id}/analytics/anova

Run one-way ANOVA across multiple groups with optional post-hoc pairwise comparisons.

---

Chi-square test

POST /api/v1/federations/{federation_id}/analytics/chi-square

Run a chi-square test of independence between two categorical variables.

Body Parameters

Parameter	Type	Required	Description
variable_1	string	Yes	First categorical variable
variable_2	string	Yes	Second categorical variable

---

List analytics queries

GET /api/v1/federations/{federation_id}/analytics/queries

List past analytics queries. Supports limit and offset pagination.

---

Retrieve an analytics query

GET /api/v1/federations/{federation_id}/analytics/queries/{query_id}

Returns query details and results.

---

Errors

Status	Error	Description
400	bad_request	Invalid or missing request fields
401	unauthorized	Missing or invalid API key
403	forbidden	Organization does not own the federation
404	not_found	Resource does not exist
429	rate_limited	Too many requests; check Retry-After
500	internal_error	Unexpected server error