Initialization & Authentication
ReflexioClient setup and API key authentication for managed Enterprise and self-hosted open-source deployments.
Initialization & Authentication
ReflexioClient
The main client class for interacting with the Reflexio API. The same ReflexioClient works against both deployment modes — only the install package, the URL, and whether you need an API key change.
from reflexio import ReflexioClient
client = ReflexioClient() # uses REFLEXIO_API_KEY env varProp
Type
Heads-up: env var divergence between SDK and CLI. The Python client reads REFLEXIO_API_URL. The reflexio CLI reads REFLEXIO_URL. Both default to https://www.reflexio.ai/. If you use both tools side-by-side, set both env vars (or pass --server-url / url_endpoint explicitly).
Setup
Enterprise
The hosted endpoint at https://www.reflexio.ai and API key authentication require a Reflexio Enterprise account.
Install the lightweight client package — it has only the SDK and a handful of pure-Python deps:
pip install reflexio-clientSet your API key as an environment variable, then create the client with no arguments:
export REFLEXIO_API_KEY="your-api-key"from reflexio import ReflexioClient
client = ReflexioClient() # url defaults to https://www.reflexio.ai/
# Ready to use immediately
response = client.get_config()You can also pass the API key directly:
client = ReflexioClient(api_key="your-api-key")The API key never expires.
Install the full open-source package — it bundles the client, the FastAPI server, and the reflexio CLI:
pip install reflexio-aiStart the local server:
reflexio services start # listens on http://localhost:8081Point the client at it. No API key is needed — the open-source server runs without authentication by default.
from reflexio import ReflexioClient
client = ReflexioClient(url_endpoint="http://localhost:8081")
# Ready to use immediately
response = client.get_config()Or use the env var:
export REFLEXIO_API_URL="http://localhost:8081"from reflexio import ReflexioClient
client = ReflexioClient() # auto-reads REFLEXIO_API_URLEnvironment variables
Variables the Python client reads. Explicit constructor parameters always take precedence.
| Variable | Purpose |
|---|---|
REFLEXIO_API_KEY | API key for authentication. Required for managed Enterprise; optional for self-hosted open-source. |
REFLEXIO_API_URL | Base URL for the API. Defaults to https://www.reflexio.ai/ (managed cloud). Set to http://localhost:8081 (or your own server) for self-hosted. |
The reflexio CLI uses a different env var for the URL: REFLEXIO_URL (not REFLEXIO_API_URL). Both default to the same managed endpoint, so you only need to think about this if you also run the CLI. See the CLI Reference for details.
Client Behavior
Synchronous API
All client methods are synchronous — no await needed. The client handles async operations internally.
Fire-and-Forget Mode
Several methods use fire-and-forget by default: the call returns None immediately and the operation runs in the background. Set wait_for_response=True to block until the server confirms.
Methods with optional fire-and-forget (wait_for_response=False by default):
delete_interaction,delete_profile,delete_request,delete_session,delete_agent_playbook,delete_user_playbook,rerun_profile_generation,rerun_playbook_generation,run_playbook_aggregation
Methods that are always fire-and-forget (no blocking option):
manual_profile_generation,manual_playbook_generation
publish_interaction always blocks on the HTTP round-trip and returns a PublishUserInteractionResponse — the wait_for_response flag controls only whether the server processes extraction synchronously before returning, not the client transport.
Caching
get_profiles and get_agent_playbooks cache results locally for 10 minutes. After publishing new data, pass force_refresh=True to bypass the cache and fetch fresh results.