Skip to main content

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.

SDK Configuration

Client Options

Both Mutagent (sync) and AsyncMutagent (async) accept the same constructor arguments:
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).
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

VariableDescriptionDefault
MUTAGENT_API_KEYYour MutagenT API keyNone (unauthenticated)
MUTAGENT_SERVER_URLAPI endpoint for the clienthttp://localhost:3003
# .env
MUTAGENT_API_KEY=mt_xxxxxxxxxxxx
MUTAGENT_SERVER_URL=https://api.mutagent.io
from mutagent import Mutagent

# No explicit args needed — env vars are auto-read
client = Mutagent()
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.

Timeout Configuration

The timeout parameter is in seconds (not milliseconds):
from mutagent import Mutagent

client = Mutagent(
    timeout=120.0,  # 2 minutes
)
Use the client as a context manager to ensure the underlying HTTP connection pool is properly closed:
from mutagent import Mutagent

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

Async context manager

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:
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:
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:
NamespaceAccessDescription
promptclient.promptPrompt CRUD and versioning
prompt_datasetsclient.prompt_datasetsDataset management
prompt_dataset_itemsclient.prompt_dataset_itemsDataset item management
prompt_evaluationsclient.prompt_evaluationsEvaluation management
optimizationclient.optimizationOptimization job control
tracesclient.tracesTrace ingestion and retrieval
experimentsclient.experimentsExperiment management
organizationsclient.organizationsOrganization management
workspacesclient.workspacesWorkspace management