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

# Overview

> Official Zavu SDK for Python

<Warning>
  **Server-side only** — This SDK is designed for server-side environments (Python servers, serverless functions). Never use it in browser/frontend code as this exposes your API key. See [Frontend Integration](/authentication#frontend-integration) for the proxy pattern.
</Warning>

The official Zavu SDK for Python provides a clean, Pythonic interface to the Zavu API with full type hints.

## Installation

```bash theme={null}
pip install zavudev
# or
uv add zavudev
# or
poetry add zavudev
```

## Requirements

* Python 3.9 or higher

## Quick Start

```python theme={null}
import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),
)

result = zavu.messages.send(
    to="+14155551234",
    text="Hello from Zavu!"
)

print(f"Message sent: {result.message.id}")
```

## Configuration

### Initialize the Client

```python theme={null}
from zavudev import Zavudev

# Basic initialization
zavu = Zavudev(
    api_key="zv_live_xxx",
)

# With custom base URL
zavu = Zavudev(
    api_key="zv_live_xxx",
    base_url="https://api.zavu.dev"
)
```

### Environment Variables

We recommend storing your API key in environment variables:

```python theme={null}
import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),
)
```

## Accessing Response Headers

Use `.with_raw_response()` to access the full HTTP response including headers:

```python theme={null}
response = zavu.messages.send.with_raw_response(
    to="+14155551234",
    text="Hello!"
)

remaining = response.headers.get("X-RateLimit-Remaining")
print(f"Remaining requests: {remaining}")

result = response.parse()
print(f"Message ID: {result.message.id}")
```

## Error Handling

```python theme={null}
from zavudev import Zavudev, ZavudevError, APIError

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),
)

try:
    zavu.messages.send(to="invalid-number", text="Hello")
except APIError as e:
    print(f"Status: {e.status_code}")
    print(f"Message: {e.message}")
except ZavudevError as e:
    print(f"Error: {e.message}")
```

### Exception Types

| Exception      | Description                |
| -------------- | -------------------------- |
| `ZavudevError` | Base exception class       |
| `APIError`     | API error with status code |

## Async Support

The SDK supports async/await with asyncio:

```python theme={null}
import asyncio
import os
from zavudev import AsyncZavudev

async def main():
    zavu = AsyncZavudev(
        api_key=os.environ.get("ZAVUDEV_API_KEY"),
    )

    result = await zavu.messages.send(
        to="+14155551234",
        text="Hello async!"
    )

    print(f"Message sent: {result.message.id}")

asyncio.run(main())
```

## Retries

The SDK supports automatic retries with configurable backoff:

```python theme={null}
from zavudev import Zavudev

zavu = Zavudev(
    api_key="zv_live_xxx",
    max_retries=3,
)

result = zavu.messages.send(
    to="+14155551234",
    text="Hello!"
)
```

## Type Hints

The SDK includes full type annotations:

```python theme={null}
from zavudev import Zavudev
from zavudev.types import Message

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),
)

result = zavu.messages.send(
    to="+14155551234",
    text="Hello!"
)

message: Message = result.message
```

## Debugging

Enable debug logging:

```python theme={null}
import logging
from zavudev import Zavudev

logging.basicConfig(level=logging.DEBUG)

zavu = Zavudev(
    api_key="zv_live_xxx",
)
```