def get_workspace_version(client, hostname):
    return client.workspace_root("GET", hostname, "/version")


def get_workspace_openapi(client, hostname):
    return client.workspace("GET", hostname, "/_openapi")


def list_openapi_paths(openapi, prefix="/api/v1/dashboard"):
    paths = openapi.get("paths", {})
    return {
        path: sorted(methods)
        for path, methods in sorted(paths.items())
        if path.startswith(prefix)
    }

# Current User And Permissions

Use this reference to inspect the authenticated workspace user and troubleshoot `401` or `403` responses.

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/me/" | jq '.result'

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/me/roles/" | jq '.result'
```

```python
me = client.workspace("GET", hostname, "/me/")["result"]
roles = client.workspace("GET", hostname, "/me/roles/")["result"]
print(me.get("username") or me.get("email"), roles)
```

Use these calls to troubleshoot `401` and `403` responses. Do not infer access from role names alone; verify the endpoint response.

For role, workspace membership, permission, or access-control changes, route to `preset-roles-permissions`.

# Menu And Feature Discovery

Use this reference to inspect workspace UI capabilities visible to the authenticated user.

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/menu/" | jq '.result'
```

```python
menu = client.workspace("GET", hostname, "/menu/")["result"]
```

The menu response is useful for checking whether workspace UI features such as SQL Lab, charts, dashboards, reports, and admin views are visible to the authenticated user.

Menu visibility is not authorization for mutations. For endpoint-specific access, verify with the target endpoint or inspect current-user permissions. For security-sensitive operations, route to the focused skill named in [workspace-api-safety.md](workspace-api-safety.md).

# Workspace Version And OpenAPI Discovery

Superset workspace API examples should be pinned to the workspace runtime where possible. The public Superset API docs may describe unreleased or broader API surfaces.

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

## Capture Workspace Version

`workspace_root()` is for Superset endpoints that sit at the server root, such as `/version` or `/healthcheck`. Use `workspace()` for all `/api/v1/...` paths.

Useful fields, when present:

| Field | Description |
|---|---|
| `version_string` | Superset runtime version string |
| `version_sha` | Short build or Git SHA |
| `build_number` | Deployment build identifier, when configured |

## Fetch Workspace OpenAPI

Fetch `GET /api/v1/_openapi` to verify that documented endpoints exist in the target workspace before writing or executing examples. If OpenAPI discovery returns `404` or is disabled in a local/dev shell, fall back to the pinned Superset source/routes for that workspace build and verify candidate endpoints with read-only metadata calls before using them.

# Workspace API Safety Classification

Default to metadata reads. HTTP method alone is not enough to decide whether an endpoint is safe.

## Metadata Reads

These are generally safe for normal discovery when the user has requested the workspace target:

| Surface | Examples |
|---|---|
| Version and OpenAPI | `/version`, `/api/v1/_openapi` |
| Current user | `/api/v1/me/`, `/api/v1/me/roles/` |
| Object metadata | dashboard, chart, dataset, database list/detail endpoints |
| Related metadata | `related`, `favorite_status`, owner summaries, menu |

## Data-Returning Reads

These can expose customer data, sample rows, SQL results, SQL text, or database structure. Before calling them, summarize the workspace, endpoint, object ID, row limit or page size, and expected returned data, then get explicit user confirmation:

| Surface | Examples |
|---|---|
| Chart data | `/api/v1/chart/{pk}/data/`, `/api/v1/chart/data` |
| Database samples | `/api/v1/database/{pk}/select_star/...` |
| Connection configuration | `/api/v1/database/{pk}/connection` |
| Distinct values | `/api/v1/dataset/distinct/{column_name}`, datasource column values |
| SQL Lab results | `/api/v1/sqllab/results/`, `/api/v1/sqllab/export/{client_id}/` |
| SQL text-bearing records | `/api/v1/query/`, `/api/v1/query/{pk}`, `/api/v1/saved_query/`, `/api/v1/saved_query/{pk}` |
| Exports | `/api/v1/assets/export/`, dashboard/chart/dataset/database/saved query exports |

Prefer page sizes and query limits that answer the user request with the least data exposure.

## Confirmation-Gated Operations

Before any `POST`, `PUT`, `PATCH`, `DELETE`, import, export, audit download, SQL execution, role/RLS change, database connection change, dataset mutation, dashboard mutation, workspace lifecycle action, invite action, member removal, guest-token creation, cache invalidation, query stop, or task cancellation:

1. Identify the exact team, workspace, dashboard, dataset, database, query, user, role, or token target.
2. Summarize the endpoint, HTTP method, request body, and expected effect.
3. Explain whether the action changes access, data, credentials, metadata, cache, or execution state.
4. Get explicit user confirmation before making the call.

For security-sensitive workflows, route to the focused Phase 5 skill: `preset-guest-tokens`, `preset-embedded-rls`, `preset-sql-execution`, `preset-database-connections`, `preset-roles-permissions`, or `preset-destructive-imports`.

Never expose credentials, bearer tokens, database passwords, SQLAlchemy URIs, access tokens, refresh tokens, signed guest tokens, or exported secret values in logs, examples, PR comments, or handoff notes.