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

# Configuration

> Configure the Ocular SDK for your environment

# SDK Configuration

**After installing the Ocular SDK, you'll need to configure it with your API credentials.** This guide covers all available configuration options.

## Basic Configuration

<Check>
  All you need to get started is your API key. Everything else has sensible defaults.
</Check>

### Direct Initialization

<Note>
  This is the simplest way to get started with the SDK for testing and development.
</Note>

You can also configure the SDK directly in your code:

```python theme={null}
from ocular import Ocular

# Initialize with direct configuration
ocular = Ocular(api_key="your_api_key_here")
```

<Warning>
  Avoid hardcoding API keys in production code. Use environment variables instead.
</Warning>

## Configuration Parameters

<Info>
  Understanding these parameters will help you optimize the SDK for your specific use case.
</Info>

The SDK accepts the following parameters during initialization:

| Parameter | Type | Default | Description |
| - | - | - | - |
| **api\_key** | string | None | **Your Ocular API key (required)** |
| **api\_url** | string | "[https://api.useocular.com](https://api.useocular.com)" | Base URL for the Ocular API |
| **timeout** | integer | 300 | Request timeout in seconds |
| **max\_retries** | integer | 3 | Maximum number of retry attempts |
| **backoff\_factor** | float | 0.5 | Exponential backoff factor for retries |
| **debug** | boolean | False | Enable detailed logging |

<Info>
  Most users will only need to set the API key. The default values work well for standard use cases.
</Info>

## Complete Example

<Tip>
  Copy this example to quickly get started with a fully configured SDK instance.
</Tip>

```python theme={null}
from ocular import Ocular

# Initialize with all available options
ocular = Ocular(
    api_key="your_api_key_here",
    api_url="https://api.useocular.com",
    timeout=300,
    max_retries=3,
    backoff_factor=0.5,
    debug=False
)

# Access your workspace
workspace = ocular.workspace("your_workspace_id")
```

## Environment Variables

<Check>
  Using environment variables is the recommended approach for production deployments.
</Check>

All configuration can be set using environment variables:

| Variable | Description | Default |
| - | - | - |
| **OCULAR\_API\_KEY** | Your API key | Required |
| **OCULAR\_API\_URL** | API base URL | "[https://api.useocular.com](https://api.useocular.com)" |
| **OCULAR\_TIMEOUT** | Request timeout | 300 |
| **OCULAR\_MAX\_RETRIES** | Max retry attempts | 3 |
| **OCULAR\_BACKOFF\_FACTOR** | Retry backoff factor | 0.5 |
| **OCULAR\_DEBUG** | Debug mode | false |

<Tip>
  Using environment variables is recommended for production environments to keep sensitive information out of your code.
</Tip>

## Using With Python dotenv

<Note>
  This approach combines the security of environment variables with the convenience of a configuration file.
</Note>

For development, you can use a `.env` file with the python-dotenv package:

```
# .env file
OCULAR_API_KEY=your_api_key_here
```

Then in your code:

```python theme={null}
from dotenv import load_dotenv
import os
from ocular import Ocular

# Load environment variables from .env file
load_dotenv()

# Initialize using values from .env
ocular = Ocular(api_key=os.environ.get("OCULAR_API_KEY"))
```

<Warning>
  Never commit your .env file to version control. Add it to your .gitignore file.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.