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

# Configuration

> SDK credentials, base URL resolution, and self-hosted setup.

`Configuration` is the credentials object every SDK module accepts. By default each module instantiates its own `Configuration` from environment variables, so most code never touches it directly. Construct one explicitly when you need to override credentials or point at a self-hosted controller.

```python theme={"dark"}
from xpander_sdk import Configuration

config = Configuration(
    api_key="your-api-key",
    organization_id="your-org-id",
)
```

## Constructor

```python theme={"dark"}
Configuration(
    api_key: Optional[str] = None,           # XPANDER_API_KEY
    base_url: Optional[str] = None,          # XPANDER_BASE_URL
    organization_id: Optional[str] = None,   # XPANDER_ORGANIZATION_ID
    agent_id: Optional[str] = None,          # XPANDER_AGENT_ID
)
```

### Attributes

| Attribute         | Type          | Default                           | Description                                                                                                                          |
| ----------------- | ------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `api_key`         | `str \| None` | `XPANDER_API_KEY` env var         | API key for authentication. Required for any cloud call.                                                                             |
| `organization_id` | `str \| None` | `XPANDER_ORGANIZATION_ID` env var | Organization identifier. Required for self-hosted controllers; optional but recommended for cloud.                                   |
| `base_url`        | `str \| None` | Auto-detected from env            | API endpoint. Defaults to `https://inbound.xpander.ai` for cloud. Set to your Agent Controller URL for self-hosted.                  |
| `agent_id`        | `str \| None` | `None`                            | Optional default agent ID. When set, methods that take `agent_id` can be called without arguments. Falls back to `XPANDER_AGENT_ID`. |

## Environment variables

The SDK reads these on import. Setting them once via `.env` or your shell removes the need to construct `Configuration` manually.

| Variable                  | Purpose                                                                                            |
| ------------------------- | -------------------------------------------------------------------------------------------------- |
| `XPANDER_API_KEY`         | API key. **Required.**                                                                             |
| `XPANDER_ORGANIZATION_ID` | Organization ID. Required for self-hosted; recommended for cloud.                                  |
| `XPANDER_BASE_URL`        | Override the API base URL.                                                                         |
| `XPANDER_AGENT_ID`        | Default agent ID. Lets `Backend()`, `Events()`, and `Agents().aget()` work without an explicit ID. |

```python theme={"dark"}
from dotenv import load_dotenv
from xpander_sdk import Configuration

load_dotenv()
config = Configuration()   # picks up XPANDER_* vars
```

## Methods

### `get_full_url() -> str`

Returns the API URL, with the organization ID appended when the controller requires it.

```python theme={"dark"}
config = Configuration(
    base_url="https://agent-controller.acme.com",
    organization_id="org_123",
)
config.get_full_url()
# 'https://agent-controller.acme.com/org_123'

config = Configuration(
    base_url="https://inbound.xpander.ai",
    organization_id="org_123",
)
config.get_full_url()
# 'https://inbound.xpander.ai'   (cloud: no prefix)
```

The org ID is appended automatically when `base_url` contains `agent-controller` or port `9016`. You don't need to do this yourself.

## Self-hosted

Use the **Agent Controller API key** generated during your Helm install (not your cloud API key) and point `base_url` at the controller:

```python theme={"dark"}
config = Configuration(
    api_key="agent-controller-api-key",
    organization_id="your-org-id",
    base_url="https://agent-controller.your-company.com",
)
```

Or via environment:

```bash theme={"dark"}
export XPANDER_API_KEY="agent-controller-api-key"
export XPANDER_ORGANIZATION_ID="your-org-id"
export XPANDER_BASE_URL="https://agent-controller.your-company.com"
```

<Warning>
  The `base_url` must point at the Agent Controller endpoint (e.g. `https://agent-controller.{your-domain}`), not the root domain. The SDK detects this URL pattern and prefixes paths with the organization ID via `get_full_url()`.
</Warning>

## Sharing config across modules

Pass the same `Configuration` to every module so they hit the same endpoint and use the same credentials:

```python theme={"dark"}
from xpander_sdk import Configuration, Agents, Tasks, KnowledgeBases

config = Configuration(api_key="...", organization_id="...")

agents = Agents(configuration=config)
tasks = Tasks(configuration=config)
kbs = KnowledgeBases(configuration=config)
```

Loaded objects (`Agent`, `Task`, `KnowledgeBase`) carry the `Configuration` they were loaded with, so subsequent method calls on them reuse it automatically.