Skip to main content

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 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. 
from xpander_sdk import Configuration

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

​
Constructor

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

AttributeTypeDefaultDescription
api_keystr | NoneXPANDER_API_KEY env varAPI key for authentication. Required for any cloud call.
organization_idstr | NoneXPANDER_ORGANIZATION_ID env varOrganization identifier. Required for self-hosted controllers; optional but recommended for cloud.
base_urlstr | NoneAuto-detected from envAPI endpoint. Defaults to https://inbound.xpander.ai for cloud. Set to your Agent Controller URL for self-hosted.
agent_idstr | NoneNoneOptional 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.
VariablePurpose
XPANDER_API_KEYAPI key. Required.
XPANDER_ORGANIZATION_IDOrganization ID. Required for self-hosted; recommended for cloud.
XPANDER_BASE_URLOverride the API base URL.
XPANDER_AGENT_IDDefault agent ID. Lets Backend(), Events(), and Agents().aget() work without an explicit ID.
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. 
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: 
config = Configuration(
    api_key="agent-controller-api-key",
    organization_id="your-org-id",
    base_url="https://agent-controller.your-company.com",
)
Or via environment: 
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"
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().

​
Sharing config across modules

Pass the same Configuration to every module so they hit the same endpoint and use the same credentials: 
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.