Configuration

The Client constructor takes everything you need to talk to the API. Every setting falls back to an environment variable, and the simplest working invocation is client = Client() with $THRUSTLAB_API_KEY set.

Constructor signature

from thrustlab import Client

client = Client(
    api_key=None,         # falls back to $THRUSTLAB_API_KEY
    base_url=None,        # falls back to $THRUSTLAB_BASE_URL, then https://thrustlab.com
    timeout=30.0,         # per-request timeout in seconds
    max_retries=3,        # max retries on 429 / 5xx / network errors
    http_client=None,     # advanced: pass a pre-built httpx.Client
)

All settings

API key

The cleanest production setup is to set the env var so the secret never touches your source tree:

export THRUSTLAB_API_KEY=key_...

from thrustlab import Client
client = Client()  # picks up $THRUSTLAB_API_KEY

For ephemeral notebooks or CI matrix jobs, the literal form works too:

client = Client(api_key="key_...")

If both are set, the constructor argument wins.

Base URL

Useful for talking to staging or a self-hosted environment:

client = Client(
    api_key="key_...",
    base_url="https://staging.thrustlab.com",
)

Trailing slashes are stripped. The path /v1/... is appended automatically.

Timeouts

timeout= is the per-request httpx timeout — it caps the wait on each HTTP attempt, not the total wall-clock time. With retries you can wait up to roughly timeout * (1 + max_retries) seconds in the worst case.

For long-running uploads or image-processing endpoints, pass a custom httpx.Client with a granular timeout:

import httpx
from thrustlab import Client

http = httpx.Client(timeout=httpx.Timeout(
    connect=10.0,
    read=300.0,
    write=60.0,
    pool=10.0,
))
client = Client(api_key="key_...", http_client=http)

When http_client= is set, the timeout= argument is ignored — you control timeouts on the httpx client.

Retries

max_retries= only applies to safe failures: HTTP 429, 500, 502, 503, 504, or transport-level errors (DNS, connect, read timeout). Validation, auth, and not-found errors are surfaced immediately. See retries & timeouts for the backoff schedule.

Custom httpx client

Reasons to drop in your own httpx.Client:

• Connection pooling across many short-lived Client instances
• Custom TLS / proxy / CA-bundle config
• Sharing transport with other tooling in your stack

import httpx
from thrustlab import Client

http = httpx.Client(
    timeout=60.0,
    proxy="http://proxy.example.com:8080",  # singular `proxy=` — httpx removed `proxies=` in 0.28
    verify="/etc/ssl/custom-ca.crt",
)
client = Client(api_key="key_...", http_client=http)

The SDK injects Authorization, Idempotency-Key, and User-Agent headers on every request — your own headers (set on the httpx client) are merged unless they collide with one of those reserved names.

Multi-tenant pattern

For tools that run as multiple end users (e.g. a CI orchestrator), construct a fresh Client per request rather than mutating a shared one:

def for_user(api_key: str) -> Client:
    return Client(api_key=api_key, http_client=SHARED_HTTPX)

Sharing one httpx.Client keeps connection pooling efficient; the SDK clients are cheap to construct.

See also

• Authentication guide
• Retries & timeouts
• Logging & debugging