​
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

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

​
Direct Initialization

This is the simplest way to get started with the SDK for testing and development.
You can also configure the SDK directly in your code: 
from ocular import Ocular

# Initialize with direct configuration
ocular = Ocular(api_key="your_api_key_here")
Avoid hardcoding API keys in production code. Use environment variables instead.

​
Configuration Parameters

Understanding these parameters will help you optimize the SDK for your specific use case.
The SDK accepts the following parameters during initialization:
ParameterTypeDefaultDescription
api_keystringNoneYour Ocular API key (required)
api_urlstring”https://api.useocular.com”Base URL for the Ocular API
timeoutinteger300Request timeout in seconds
max_retriesinteger3Maximum number of retry attempts
backoff_factorfloat0.5Exponential backoff factor for retries
debugbooleanFalseEnable detailed logging
Most users will only need to set the API key. The default values work well for standard use cases.

​
Complete Example

Copy this example to quickly get started with a fully configured SDK instance.
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

Using environment variables is the recommended approach for production deployments.
All configuration can be set using environment variables:
VariableDescriptionDefault
OCULAR_API_KEYYour API keyRequired
OCULAR_API_URLAPI base URL”https://api.useocular.com”
OCULAR_TIMEOUTRequest timeout300
OCULAR_MAX_RETRIESMax retry attempts3
OCULAR_BACKOFF_FACTORRetry backoff factor0.5
OCULAR_DEBUGDebug modefalse
Using environment variables is recommended for production environments to keep sensitive information out of your code.

​
Using With Python dotenv

This approach combines the security of environment variables with the convenience of a configuration file.
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: 
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"))
Never commit your .env file to version control. Add it to your .gitignore file.