> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.slotflow.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.slotflow.dev/_mcp/server.

# Python SDK

> Official Python SDK for the Slotflow API.

The official Slotflow SDK for Python. Supports both synchronous and asynchronous usage, with typed errors and full API coverage.

## Installation

```bash
pip install slotflow
```

## Quick example

```python
from slotflow import Slotflow

client = Slotflow(api_key="sk_live_your_api_key")

# Find available slots
response = client.slots.list(
    "HUMAN_ID",
    date_from="2026-03-15",
    date_to="2026-03-20",
    duration=30,
)

# Book the first slot
booking = client.bookings.create(
    human_id="HUMAN_ID",
    starts_at=response["slots"][0]["starts_at"],
    duration=30,
    attendee_name="Alex Rivera",
    attendee_email="alex@startup.io",
    metadata={
        "lead_id": "lead_8294",
        "source": "ai_sdr",
    },
)
```

## Async support

```python
from slotflow import AsyncSlotflow

client = AsyncSlotflow(api_key="sk_live_your_api_key")

response = await client.slots.list(
    "HUMAN_ID",
    date_from="2026-03-15",
    date_to="2026-03-20",
    duration=30,
)
```

Both clients support context managers:

```python
with Slotflow(api_key="sk_live_...") as client:
    humans = client.humans.list()

async with AsyncSlotflow(api_key="sk_live_...") as client:
    humans = await client.humans.list()
```

## Resources

All API resources are available as methods on the client:

| Resource                    | Methods                           |
| --------------------------- | --------------------------------- |
| `client.humans`             | `create`, `get`, `list`, `delete` |
| `client.availability`       | `set`                             |
| `client.schedule_overrides` | `create`, `list`, `delete`        |
| `client.slots`              | `list`                            |
| `client.bookings`           | `create`, `list`, `cancel`        |
| `client.webhooks`           | `create`, `list`, `delete`        |

## Error handling

The SDK raises typed exceptions you can catch and handle:

```python
from slotflow import Slotflow, ConflictError, PaymentRequiredError, NotFoundError, ValidationError

client = Slotflow(api_key="sk_live_your_api_key")

try:
    booking = client.bookings.create(
        human_id="HUMAN_ID",
        starts_at="2026-03-15T14:00:00.000Z",
        duration=30,
        attendee_name="Alex Rivera",
    )
except ConflictError:
    # 409 — slot was just booked by someone else
    # Re-query slots and try the next one
    pass
except PaymentRequiredError:
    # 402 — booking limit reached
    pass
except NotFoundError:
    # 404 — human not found
    pass
except ValidationError as e:
    # 422 — validation error (outside working hours, invalid duration, etc.)
    print(e.code, e.message)
```

## Configuration

```python
client = Slotflow(
    api_key="sk_live_your_api_key",

    # Override the default base URL
    base_url="https://api.slotflow.dev",

    # Override the default timeout (seconds)
    timeout=30.0,
)
```

## Requirements

* Python 3.8+
* Get your API key from the [Slotflow Dashboard](https://app.slotflow.dev)

## Links

* [PyPI package](https://pypi.org/project/slotflow/)
* [GitHub repository](https://github.com/nestorknf/slotflow-python)
* [API Reference](/api-reference)