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

# Configuration

> Configure the MutagenT Python SDK

# SDK Configuration

## Client Options

Both `Mutagent` (sync) and `AsyncMutagent` (async) accept the same constructor arguments:

```python theme={null}
from mutagent import Mutagent, AsyncMutagent
import httpx

client = Mutagent(
    api_key="mt_xxxxxxxxxxxx",        # API key (sends x-api-key header); falls back to MUTAGENT_API_KEY env var
    server_url="https://api.mutagent.io",  # API endpoint; falls back to MUTAGENT_SERVER_URL env var (default: http://localhost:3003)
    timeout=60.0,                     # Request timeout in seconds (default: 60)
    http_client=httpx.Client(),       # Optional custom httpx.Client
    allow_insecure_http=False,        # Set True to allow plain HTTP to non-local hosts
)
```

## Authentication

The SDK reads your API key from the constructor or from the `MUTAGENT_API_KEY` environment variable. If neither is provided, requests will be sent without authentication (resulting in 401 responses).

<Mermaid>
  flowchart TD
  Start\["SDK Request"] --> Check{"api_key kwarg?"}
  Check -->|"Yes"| ApiKey\["Send x-api-key header"]
  Check -->|"No"| EnvVar{"MUTAGENT_API_KEY env?"}
  EnvVar -->|"Yes"| ApiKey
  EnvVar -->|"No"| NoAuth\["Request sent without auth key"]

  style Start fill:#7C3AED,color:#fff
  style ApiKey fill:#06B6D4,color:#000
  style NoAuth fill:#EF4444,color:#fff
</Mermaid>

### API Key (Recommended)

```python theme={null}
from mutagent import Mutagent

# Simplest: SDK auto-reads MUTAGENT_API_KEY env var
client = Mutagent()

# Explicit: pass API key directly
client = Mutagent(api_key="mt_xxxxxxxxxxxx")

# With production server URL
client = Mutagent(
    api_key="mt_xxxxxxxxxxxx",
    server_url="https://api.mutagent.io",
)
```

## Environment Variables

| Variable              | Description                 | Default                 |
| --------------------- | --------------------------- | ----------------------- |
| `MUTAGENT_API_KEY`    | Your MutagenT API key       | None (unauthenticated)  |
| `MUTAGENT_SERVER_URL` | API endpoint for the client | `http://localhost:3003` |

```bash theme={null}
# .env
MUTAGENT_API_KEY=mt_xxxxxxxxxxxx
MUTAGENT_SERVER_URL=https://api.mutagent.io
```

```python theme={null}
from mutagent import Mutagent

# No explicit args needed — env vars are auto-read
client = Mutagent()
```

<Note>
  The default `server_url` is `http://localhost:3003` (local dev). For production, always set `MUTAGENT_SERVER_URL=https://api.mutagent.io` or pass it explicitly. The SDK enforces HTTPS for non-local hosts unless `allow_insecure_http=True` is passed.
</Note>

## Timeout Configuration

The `timeout` parameter is in **seconds** (not milliseconds):

```python theme={null}
from mutagent import Mutagent

client = Mutagent(
    timeout=120.0,  # 2 minutes
)
```

## Context Manager (Recommended)

Use the client as a context manager to ensure the underlying HTTP connection pool is properly closed:

```python theme={null}
from mutagent import Mutagent

with Mutagent() as client:
    prompts = client.prompt.list_prompts()
```

### Async context manager

```python theme={null}
import asyncio
from mutagent import AsyncMutagent

async def main():
    async with AsyncMutagent() as client:
        prompts = await client.prompt.list_prompts()

asyncio.run(main())
```

## Custom HTTP Client

For advanced use cases (proxies, custom TLS, request interceptors), provide your own `httpx.Client`:

```python theme={null}
import httpx
from mutagent import Mutagent

# Example: custom proxy
transport = httpx.HTTPTransport(proxy="http://proxy.example.com:8080")
custom_client = httpx.Client(transport=transport)

client = Mutagent(
    http_client=custom_client,
)
```

For async:

```python theme={null}
import httpx
from mutagent import AsyncMutagent

async_client = httpx.AsyncClient(
    headers={"X-Custom-Header": "value"},
)

client = AsyncMutagent(
    http_client=async_client,
)
```

## Namespace Reference

The client exposes these namespaces. Each namespace groups related API methods:

| Namespace              | Access                        | Description                   |
| ---------------------- | ----------------------------- | ----------------------------- |
| `prompt`               | `client.prompt`               | Prompt CRUD and versioning    |
| `prompt_datasets`      | `client.prompt_datasets`      | Dataset management            |
| `prompt_dataset_items` | `client.prompt_dataset_items` | Dataset item management       |
| `prompt_evaluations`   | `client.prompt_evaluations`   | Evaluation management         |
| `optimization`         | `client.optimization`         | Optimization job control      |
| `traces`               | `client.traces`               | Trace ingestion and retrieval |
| `experiments`          | `client.experiments`          | Experiment management         |
| `organizations`        | `client.organizations`        | Organization management       |
| `workspaces`           | `client.workspaces`           | Workspace management          |