Appearance
Clean Room API
REST API for managing federated clean rooms: creation, invitation, attestation, execution, result approval, and provenance access.
Base path: /api/clean-room
All endpoints require Bearer token authentication.
Endpoints
Create a Clean Room
POST /api/clean-roomThe caller's organization becomes the initiator.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Clean room name |
description | string | no | Description |
computation_template | string | no | Initial computation code |
Response: The created clean room object with id, name, status: "draft", initiator_org_id, timestamps.
List Clean Rooms
GET /api/clean-room?status={status}List clean rooms the caller's organization participates in.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by status (e.g., draft, ready, escrowed) |
Response
json
{
"clean_rooms": [{ "id": "...", "name": "...", "status": "ready" }]
}Get a Clean Room
GET /api/clean-room/{clean_room_id}Returns clean room details including all participants. Only accessible to participating organizations (403 otherwise).
Response
json
{
"id": "cr-abc123",
"name": "M&A Revenue Overlap",
"status": "ready",
"participants": [
{ "organization_id": "org-1", "role": "initiator", "status": "attested" },
{ "organization_id": "org-2", "role": "participant", "status": "attested" }
]
}Invite an Organization
POST /api/clean-room/{clean_room_id}/inviteRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
target_org_id | string | yes | Organization ID to invite |
Accept an Invitation
POST /api/clean-room/{clean_room_id}/acceptAccept an invitation to join the clean room. No request body required.
Set Computation Template
PUT /api/clean-room/{clean_room_id}/templateSet the computation code and generate an attestation bundle. Moves the clean room from draft to attesting status.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
computation_template | string | yes | The computation code |
sandbox_config | object | no | Sandbox configuration overrides |
Response
json
{
"status": "attesting",
"attestation_bundle": {
"image_hash": "sha256:...",
"code_hash": "sha256:...",
"config_hash": "sha256:...",
"combined_hash": "sha256:..."
}
}Submit Attestation
POST /api/clean-room/{clean_room_id}/attestSubmit the calling organization's attestation that the computation environment has been reviewed and approved.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
bundle_hash | string | yes | The combined_hash from the attestation bundle |
Response
json
{
"attested": true,
"all_attested": true,
"status": "ready"
}When all participants have attested, the status moves to ready.
Get Attestation Status
GET /api/clean-room/{clean_room_id}/attestationResponse
json
{
"attestations": [
{ "organization_id": "org-1", "attested": true, "timestamp": "..." },
{ "organization_id": "org-2", "attested": false }
]
}Release Decision
POST /api/clean-room/{clean_room_id}/releaseApprove or reject the release of escrowed results.
Request Body
| Field | Type | Required | Values |
|---|---|---|---|
action | string | yes | approve or reject |
reason | string | no | Rejection reason |
All participants must approve for results to be released. If any participant rejects, encrypted results are destroyed.
Get Results
GET /api/clean-room/{clean_room_id}/resultsRetrieve released results. Returns different payloads depending on state:
Escrowed (not yet released)
json
{
"status": "escrowed",
"summary": { "...": "..." },
"released": false
}Released (all parties approved)
json
{
"status": "released",
"released": true,
"result": { "...": "..." }
}Get Provenance
GET /api/clean-room/{clean_room_id}/provenanceGet the calling organization's provenance records for a clean room. Each org sees only its own provenance data.
Response
json
{
"provenance": [
{
"computation_id": "...",
"tool_name": "...",
"input_lineage": "...",
"result_hash": "..."
}
]
}Status Lifecycle
draft → attesting → ready → executing → escrowed → released
→ rejected
draft / attesting → expired (TTL exceeded)Related
- Clean Room Feature -- feature overview and use cases
- PhD API -- scientific computation endpoints
- SDK Reference -- Python client library