def list_teams(client):
    return client.mgmt("GET", "/teams/")["payload"]


def get_team(client, team_name):
    return client.mgmt("GET", f"/teams/{team_name}/")["payload"]


def list_workspaces(client, team_name):
    return client.mgmt("GET", f"/teams/{team_name}/workspaces/")["payload"]


def get_workspace(client, team_name, workspace_id):
    return client.mgmt(
        "GET",
        f"/teams/{team_name}/workspaces/{workspace_id}/",
    )["payload"]


def get_workspace_hostname(client, team_name, workspace_title):
    for ws in list_workspaces(client, team_name):
        if ws["title"].lower() == workspace_title.lower():
            return ws["hostname"]
    raise ValueError(f"Workspace '{workspace_title}' not found in team '{team_name}'")


def iter_workspaces(client):
    for team in list_teams(client):
        for ws in list_workspaces(client, team["name"]):
            yield team, ws


def workspace_is_ready(workspace):
    return workspace["workspace_status"] == "READY"

# Team And Workspace Discovery Reference

## Key Concepts

| Term | Description |
|---|---|
| Team | The top-level organizational unit in Preset. Maps to a Preset subscription. |
| Workspace | An isolated Superset instance inside a team. |
| Team name | Stable team identifier used in Management API paths. Returned by `GET /teams/` as `name`. |
| Workspace hostname | Unique host of a workspace's Superset API. |

Production examples use `https://api.app.preset.io/v1`. For sandbox or staging environments, set `PRESET_API_BASE` as described in `preset-api` and use that base URL for Management API calls.

Reusable Python snippets live in `examples/workspace_discovery.py`; load that file only when implementation detail is needed.

## Endpoints

| Goal | Method and path |
|---|---|
| List teams | `GET /teams/` |
| Get one team | `GET /teams/{team_name}/` |
| List workspaces for a team | `GET /teams/{team_name}/workspaces/` |
| Get one workspace | `GET /teams/{team_name}/workspaces/{workspace_id}/` |

Common response fields:

| Field | Description |
|---|---|
| `name` | Stable team identifier used in subsequent API paths |
| `title` | Human-readable team title |
| `id` | Numeric team ID |
| `created_on` | ISO 8601 creation timestamp |

## Workspace Fields

Common response fields:

| Field | Description |
|---|---|
| `id` | Numeric workspace ID |
| `title` | Human-readable workspace title |
| `hostname` | Hostname for the workspace's Superset API |
| `workspace_status` | Status enum such as `READY`, `HIBERNATED`, `UPGRADING`, or `ERROR` |
| `region` | Cloud region |

## Resolve Workspace Hostname By Title

When a user specifies a particular team or workspace by name, filter listing results to find the matching hostname rather than assuming a specific value.

## Iterate Across All Workspaces

Use this fan-out pattern only for inventory or admin tasks. For single-target user requests, resolve the specific team and workspace by name instead of scanning every workspace.

## Check Workspace Health Before Workspace API Calls

Only make workspace Superset API calls when `workspace_status == "READY"`. If a workspace is hibernated, upgrading, or in error, report that state instead of assuming workspace API availability.

# Membership Reference

Use this reference for read-only workspace membership listing. Use `preset-admin` for team membership management, invite lifecycle workflows, workspace role changes, seat-limit checks, and role identifier guidance.

## List Workspace Members

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.app.preset.io/v1/teams/{team_name}/workspaces/{workspace_id}/memberships/?page_number=1&page_size=100" \
  | jq '.payload'
```

```python
members = client.mgmt(
    "GET",
    f"/teams/{team_name}/workspaces/{workspace_id}/memberships/?page_number=1&page_size=100",
)["payload"]
```

Common response fields:

| Field | Description |
|---|---|
| `user.id` | Numeric user ID |
| `user.email` | Member email address |
| `user.username` | Member Preset username |
| `user.first_name` | Member first name |
| `user.last_name` | Member last name |
| `workspace_role.role_identifier` | Preset workspace role identifier |
| `workspace_role.name` | Workspace role display name |
| `workspace_role.role_name` | Workspace role name |
| `is_role_from_group` | Whether the workspace role is inherited from a user group |

The response is paginated. Use `preset-admin` before acting on any user ID or role identifier from this response.