Logo IconGuided Mind
v2.4Sign In
Python SDK

Basic Usage

Initialising the Client and authenticating with your API key.

The Client class is the single entry point for all SDK operations. Instantiate it once and reuse it across your application — it maintains an internal connection pool.

Initialising the Client

from guidedmind import Client
 
# Option 1 — reads GUIDEDMIND_API_KEY from the environment automatically
client = Client()
 
# Option 2 — pass the key explicitly (always prefer env vars in production)
client = Client(api_key="gm_live_...")
 
# Option 3 — full configuration
client = Client(
    api_key="gm_live_...",
    base_url="https://api.guidedmind.ai",
    timeout=30.0,
    max_retries=3,
)

Never hardcode your API key in source code or commit it to version control. Use the GUIDEDMIND_API_KEY environment variable or a secrets manager.

Constructor Parameters

ParameterTypeDefaultDescription
api_keystr | NoneNoneAPI key. Falls back to the GUIDEDMIND_API_KEY environment variable if omitted.
base_urlstr"https://api.guidedmind.ai"API base URL. Must use HTTPS — plaintext HTTP is rejected at init time.
timeoutfloat30.0Per-request timeout in seconds.
max_retriesint3Maximum retry attempts on 429 and 5xx responses before raising an error.

Setting the Environment Variable

# .env file (add to .gitignore)
GUIDEDMIND_API_KEY=gm_live_your_key_here
# Load from .env in development (python-dotenv)
from dotenv import load_dotenv
load_dotenv()
 
from guidedmind import Client
client = Client()  # picks up the env var automatically

Verifying the Connection

A lightweight way to confirm your key is valid before running real queries:

from guidedmind import Client, AuthenticationError
 
try:
    client = Client()
    # Any real call will validate the key — search with an empty-ish query
    client.search(query="ping", limit=1)
    print("Connection OK")
except AuthenticationError:
    print("Invalid API key — check GUIDEDMIND_API_KEY")
← PreviousInstallationNext →RAG Search