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

# Python SDK

> Official Python SDK for Buena.ai API

The official Python SDK for the Buena.ai API provides a convenient way to integrate Buena.ai's lead generation and LinkedIn automation features into your Python applications.

<Info>
  **🔄 Auto-Generated**: Generated with [OpenAPI
  Generator](https://openapi-generator.tech) and automatically updated via
  GitHub Actions.
</Info>

## 📦 Installation

Install the SDK using pip:

```bash theme={null}
pip install buena-sdk
```

## 🚀 Quick Start

```python theme={null}
import buena_sdk
from buena_sdk.rest import ApiException
from buena_sdk.api.default_api import DefaultApi

# Initialize the client
configuration = buena_sdk.Configuration(
    host="https://api.buena.ai/api/v2"
)
configuration.api_key['ApiKeyAuth'] = 'your-api-key'

# Create API client
with buena_sdk.ApiClient(configuration) as api_client:
    api_instance = DefaultApi(api_client)

    try:
        # List leads
        leads = api_instance.list_leads()
        print(leads)

        # Create a new lead
        lead_request = buena_sdk.CreateLeadRequest(
            first_name="John",
            last_name="Doe",
            email="john@example.com",
            company="Example Corp"
        )
        new_lead = api_instance.create_lead(lead_request)
        print(f"Created lead: {new_lead}")

    except ApiException as e:
        print(f"Exception when calling API: {e}")
```

## 🔧 Configuration

```python theme={null}
import buena_sdk

# Basic configuration
configuration = buena_sdk.Configuration(
    host='https://api.buena.ai/api/v2',  # API base URL
)

# Set API key
configuration.api_key['ApiKeyAuth'] = 'your-api-key'

# Optional: Configure timeouts and retries
configuration.connection_pool_maxsize = 10
configuration.proxy = None  # Set proxy if needed
configuration.verify_ssl = True  # SSL verification
configuration.ssl_ca_cert = None  # Custom CA certificate
```

## 📋 Available Operations

### Leads Management

* `api_instance.list_leads()` - List all leads with optional filtering
* `api_instance.create_lead(create_lead_request)` - Create a new lead
* `api_instance.get_lead(lead_id)` - Get a specific lead
* `api_instance.update_lead(lead_id, update_lead_request)` - Update an existing lead
* `api_instance.delete_lead(lead_id)` - Delete a lead

### API Keys Management

* `api_instance.list_api_keys()` - List all API keys
* `api_instance.create_api_key(create_api_key_request)` - Create a new API key

### Health Check

* `api_instance.health_check()` - Check API status

## 🔗 Repository & Advanced Usage

For complete documentation, examples, and source code:

<Card title="📁 Python SDK Repository" icon="github" href="https://github.com/buena-ai/sdks/tree/main/python">
  Access the full SDK source code, advanced examples, and detailed
  documentation.
</Card>

## 💡 Features

✅ **Type Hints** - Full type annotations for better IDE support\
✅ **Async Support** - Optional async/await patterns with asyncio\
✅ **Error Handling** - Comprehensive exception handling\
✅ **Pagination** - Built-in pagination support for large datasets\
✅ **Auto Updates** - Automatically updated from OpenAPI spec via GitHub Actions\
✅ **Production Ready** - Battle-tested OpenAPI Generator with robust HTTP client

## 🔄 Async Support

The SDK supports async/await patterns using the async client:

```python theme={null}
import asyncio
import buena_sdk
from buena_sdk.api.default_api import DefaultApi
from buena_sdk.rest import ApiException

async def main():
    configuration = buena_sdk.Configuration(
        host="https://api.buena.ai/api/v2"
    )
    configuration.api_key['ApiKeyAuth'] = 'your-api-key'

    async with buena_sdk.ApiClient(configuration) as api_client:
        api_instance = DefaultApi(api_client)

        try:
            # List leads asynchronously
            leads = await api_instance.list_leads()
            print(leads)

            # Create lead asynchronously
            lead_request = buena_sdk.CreateLeadRequest(
                first_name="Jane",
                last_name="Smith",
                email="jane@example.com"
            )
            new_lead = await api_instance.create_lead(lead_request)
            print(f"Created lead: {new_lead}")

        except ApiException as e:
            print(f"Exception when calling API: {e}")

# Run async function
asyncio.run(main())
```

## 🛠️ Error Handling

```python theme={null}
from buena_sdk.rest import ApiException

try:
    leads = api_instance.list_leads()
except ApiException as e:
    print(f"Exception when calling DefaultApi->list_leads: {e}")

    # Handle specific error codes
    if e.status == 401:
        print('Invalid API key - check your authentication')
    elif e.status == 429:
        print('Rate limit exceeded - please retry later')
    elif e.status == 500:
        print('Server error - please contact support')
    else:
        print(f'API error {e.status}: {e.reason}')

except Exception as e:
    print(f"Unexpected error: {e}")
```

## 📄 Working with Models

```python theme={null}
import buena_sdk

# Create a lead object
lead_request = buena_sdk.CreateLeadRequest(
    first_name="John",
    last_name="Doe",
    email="john@example.com",
    company="Example Corp",
    phone="+1234567890",
    linkedin_url="https://linkedin.com/in/johndoe"
)

# Access lead properties
print(f"Creating lead: {lead_request.first_name} {lead_request.last_name}")
print(f"Email: {lead_request.email}")
```

## 🆘 Support

* **📖 Full Documentation**: [SDK Repository](https://github.com/buena-ai/sdks)
* **💬 Discord**: [Join our community](https://discord.gg/Hb4Y9Rgh6E)
* **📧 Email**: [support@buena.ai](mailto:support@buena.ai)