Workrooms

client.workrooms manages workroom metadata, lifecycle, membership, session bindings and exports. Lifecycle reads and restoration return typed, forward-compatible models. The server enforces the caller's permissions for every operation.

Inspect and restore a workroom

import os

from kamiwaza_sdk import KamiwazaClient

client = KamiwazaClient(
    base_url=os.environ["KAMIWAZA_BASE_URL"],  # include /api
    api_key=os.environ["KAMIWAZA_API_KEY"],
)
room_id = os.environ["KAMIWAZA_WORKROOM_ID"]

summary = client.workrooms.get_lifecycle_summary(room_id)
print(summary.status, summary.catalog_entry_count, summary.retention_policy)

preview = client.workrooms.get_deletion_preview(room_id)
for impact in preview.impact_items:
    print(impact.type, impact.count, impact.description)
for member in preview.members_losing_access:
    print(member.user_id, member.role)

# Restore an archived workroom when you intend to make it active again.
restored = client.workrooms.restore(room_id)
assert restored.status == "active"

get_lifecycle_summary reads resource and membership counts, ingestion dates, and retention details. get_deletion_preview describes deletion's effect without deleting the workroom. restore sends a restoration request and returns the updated workroom. Invalid UUID strings raise ValueError before a request; unavailable workrooms raise NotFoundError. Authorization refusals and state conflicts remain APIError responses from the server.

The integration scenario tests/integration/test_workroom_admin_live.py::test_owner_archives_restores_previews_and_deletes_a_workroom uses these methods to check archive/read-only behavior, restoration, the effect of one known dataset, membership impact and deletion. It is selected by pytest -m integration and retains the existing disposable-identity opt-in and fixture requirements. Collection alone does not establish a live pass.

Share and manage membership

Membership methods require the caller's ordinary Workroom permissions. Roster and history reads require view access; lookup and changes require owner-level authority. The SDK preserves server refusals and never confirms sharing or active-session removal on the caller's behalf.

from kamiwaza_sdk.schemas.workroom_membership import (
    AddWorkroomMember, UpdateWorkroomMember, TransferWorkroomOwnership,
)

roster = client.workrooms.list_members(room_id, include_inactive=True)
person = client.workrooms.lookup_member(room_id, email="member@example.com")

# Set attested=True only after confirming that sharing this room is intended.
invited = client.workrooms.add_member(
    room_id, AddWorkroomMember(email="member@example.com", role="viewer", attested=True)
)
client.workrooms.update_member(room_id, invited.user_id, UpdateWorkroomMember(role="editor"))
history = client.workrooms.list_role_history(room_id, limit=100)

Use the returned user_id for membership operations: it is a subject identifier and can differ from the local user-administration record ID. Response roles and future fields are retained when a newer server adds them.

remove_member(room_id, user_id) leaves an active-session conflict as an error. After reviewing that conflict, an explicit confirm_active_sessions=True requests removal and Core's best-effort session termination. The response alone does not prove every runtime session ended.

transfer_ownership(room_id, TransferWorkroomOwnership(user_id=...)) changes the primary owner and retains the previous member as an editor by default. keep_previous_owner=True retains their owner role; it is not a switch for retaining membership. previous_owner_role chooses their role when that switch is false. Transfers and membership mutations require approval in agent tools.

The integration node test_workroom_membership_live.py::test_membership_roles_transfer_and_confirmed_removal uses disposable non-admin identities, round-trips ownership, and tests the explicit active-session confirmation with a separately authenticated control. It is selected by pytest -m integration with KAMIWAZA_TEST_DISPOSABLE_IDENTITIES=1. Its capability mapping supplements the existing UI journey; UI refresh, connector-content compatibility, global-room protection and complete runtime-session termination remain unverified.