Skip to content

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

The caller's organization becomes the initiator.

Request Body

FieldTypeRequiredDescription
namestringyesClean room name
descriptionstringnoDescription
computation_templatestringnoInitial 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

ParameterTypeDescription
statusstringFilter 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}/invite

Request Body

FieldTypeRequiredDescription
target_org_idstringyesOrganization ID to invite

Accept an Invitation ​

POST /api/clean-room/{clean_room_id}/accept

Accept an invitation to join the clean room. No request body required.


Set Computation Template ​

PUT /api/clean-room/{clean_room_id}/template

Set the computation code and generate an attestation bundle. Moves the clean room from draft to attesting status.

Request Body

FieldTypeRequiredDescription
computation_templatestringyesThe computation code
sandbox_configobjectnoSandbox 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}/attest

Submit the calling organization's attestation that the computation environment has been reviewed and approved.

Request Body

FieldTypeRequiredDescription
bundle_hashstringyesThe 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}/attestation

Response

json
{
  "attestations": [
    { "organization_id": "org-1", "attested": true, "timestamp": "..." },
    { "organization_id": "org-2", "attested": false }
  ]
}

Release Decision ​

POST /api/clean-room/{clean_room_id}/release

Approve or reject the release of escrowed results.

Request Body

FieldTypeRequiredValues
actionstringyesapprove or reject
reasonstringnoRejection 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}/results

Retrieve 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}/provenance

Get 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)

SOC 2 Type II Certified | BAA Available | HIPAA-Ready