> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nexspace365.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Install and use the NexSpace Python SDK

# Python SDK

## Installation

```bash theme={null}
pip install nexspace
```

Requires Python 3.9+.

## Quick Start

```python theme={null}
from nexspace import NexSpace

client = NexSpace(api_key="nex_live_YOUR_KEY")

# List facilities
facilities = client.facilities.list()

# Search staff
staff = client.staff.search(query="Jane", specialty="RN", facility_id=12)

# Get a staff member
member = client.staff.get(789)
```

## Configuration

```python theme={null}
client = NexSpace(
    api_key="nex_live_...",
    base_url="https://api.nexspace365.com",  # default
    version="2026-05-10",                 # pin API version
    max_retries=3,                        # default
    timeout=30.0,                         # 30s default
)
```

## Resources

### Facilities

```python theme={null}
facilities = client.facilities.list()
facility = client.facilities.get(12)
```

### Staff

```python theme={null}
results = client.staff.search(query="Smith", limit=10)
member = client.staff.get(789)
```

### Shifts

```python theme={null}
shifts = client.shifts.list(facility_id=12, status="open")
assigned = client.shifts.assign(456, staff_ids=[789])
```

### API Keys

```python theme={null}
keys = client.api_keys.list()
new_key = client.api_keys.create(
    name="CI Pipeline",
    scopes=["shifts:read", "staff:read"],
)
```

## Pydantic Models

All responses are Pydantic v2 models with full type information:

```python theme={null}
from nexspace.types import Facility, Staff, Shift

facilities: list[Facility] = client.facilities.list()
print(facilities[0].name)  # IDE autocomplete works
```

## Error Handling

```python theme={null}
from nexspace import NexSpaceError

try:
    client.shifts.assign(456, staff_ids=[789])
except NexSpaceError as e:
    print(e.code)        # "FORBIDDEN"
    print(e.suggestion)  # "Rotate your API key to include..."
    print(e.retryable)   # False
```

## Async Support

```python theme={null}
from nexspace import AsyncNexSpace

async_client = AsyncNexSpace(api_key="nex_live_YOUR_KEY")
facilities = await async_client.facilities.list()
```