> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Spaces

> Manage Arize spaces programmatically. Create, list, retrieve, and update spaces within your organization.

<Note>
  The `spaces` client methods are currently in **BETA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

Manage spaces programmatically. Create, list, retrieve, and update spaces within your Arize organization.

## Key Capabilities

* List spaces you have access to within an organization
* Retrieve space details by ID
* Create new spaces within an organization
* Update a space's name or description
* Delete spaces and all their resources
* Add or remove users (space memberships)

## List Spaces

List all spaces you have access to, with optional filtering by organization or name.

```python theme={null}
resp = client.spaces.list(
    organization_id="your-org-id",  # optional
    name="my-space",                # optional substring filter
    limit=50,
)

for space in resp.spaces:
    print(space.id, space.name)
```

For details on pagination, field introspection, and data conversion (to dict/JSON/DataFrame), see [Response Objects](/api-clients/python/version-8/overview#response-objects).

## Create a Space

Create a new space within an organization. Space names must be unique within the target organization.

```python theme={null}
space = client.spaces.create(
    name="my-new-space",
    organization_id="your-org-id",
    description="Optional description of the space",  # optional
)

print(space.id, space.name)
```

## Get a Space

Retrieve a specific space by name or ID.

```python theme={null}
space = client.spaces.get(space="your-space-name-or-id")

print(space.id, space.name)
```

## Update a Space

Update an existing space's name or description. At least one of `name` or `description` must be provided.

```python theme={null}
space = client.spaces.update(
    space="your-space-name-or-id",
    name="updated-space-name",
    description="Updated description",  # optional
)

print(space.id, space.name)
```

## Delete a Space

<Warning>This operation is irreversible. Deleting a space permanently removes all resources that belong to it (models, monitors, dashboards, datasets, custom metrics, etc.).</Warning>

```python theme={null}
client.spaces.delete(space="your-space-name-or-id")
```

## Add a User to a Space

<Note>
  The `spaces.add_user` method is currently in **ALPHA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

Add a user to a space, or update their role if they're already a member (upsert). The user must already be a member of the space's parent organization — auto-enrollment is not performed.

Role constraints:

* Users with an `annotator` account role can only be assigned the `annotator` predefined space role.
* Users with a non-annotator account role cannot be assigned the `annotator` predefined space role.

Requires space admin (for predefined roles) or `ROLE_BINDING_CREATE` permission (for custom roles).

```python theme={null}
from arize.spaces.types import PredefinedSpaceRole

membership = client.spaces.add_user(
    space="your-space-name-or-id",
    user_id="your-user-id",
    role=PredefinedSpaceRole(name="member"),  # "admin", "member", "read-only", or "annotator"
)

print(membership.id, membership.user_id, membership.role)
```

To assign a custom RBAC role instead:

```python theme={null}
from arize.spaces.types import CustomSpaceRole

membership = client.spaces.add_user(
    space="your-space-name-or-id",
    user_id="your-user-id",
    role=CustomSpaceRole(id="your-custom-role-id"),
)
```

## Remove a User from a Space

<Note>
  The `spaces.remove_user` method is currently in **ALPHA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

Remove a user from a space. This removes both the legacy space-membership row and any RBAC role bindings for the user on this space.

Requires space admin (legacy auth) or `ROLE_BINDING_DELETE` permission (RBAC).

```python theme={null}
client.spaces.remove_user(
    space="your-space-name-or-id",
    user_id="your-user-id",
)

print("User removed from space")
```