Skip to main content

SDK Configuration

Client Options

import { Mutagent } from '@mutagent/sdk';
import type { SDKOptions } from '@mutagent/sdk';

const client = new Mutagent({
  // Authentication (optional if MUTAGENT_API_KEY env var is set)
  security: {
    apiKey?: string,       // API key (sends x-api-key header)
    bearerAuth?: string,   // OAuth token (sends Authorization: Bearer header)
  },

  // Optional configuration
  serverURL?: string,      // Custom API URL (default: https://api.mutagent.io)
  serverIdx?: number,      // Server index (0 = default)
  timeoutMs?: number,      // Request timeout in ms
  retryConfig?: RetryConfig,

  // Advanced
  httpClient?: HTTPClient, // Custom HTTP client
  debugLogger?: Logger,    // Debug logging
});

Authentication

The SDK supports two authentication methods. The apiKey is tried first; if present, bearerAuth is skipped.
import { Mutagent } from '@mutagent/sdk';

// Simplest: SDK auto-reads MUTAGENT_API_KEY env var
const client = new Mutagent();

// Explicit: pass API key directly
const client = new Mutagent({
  security: { apiKey: process.env.MUTAGENT_API_KEY },
});

// With custom server
const client = new Mutagent({
  security: { apiKey: process.env.MUTAGENT_API_KEY },
  serverURL: 'https://api.mutagent.io',
});

Bearer Auth (OAuth)

For OAuth flows, use bearerAuth:
const client = new Mutagent({
  security: { bearerAuth: 'your-oauth-token' },
});
For dynamic token refresh, pass a security function:
const client = new Mutagent({
  security: async () => ({
    bearerAuth: await refreshToken(),
  }),
});

Environment Variables

The SDK automatically reads these environment variables:
VariableHeader SentPurpose
MUTAGENT_API_KEYx-api-keyAPI key authentication
MUTAGENT_BEARER_AUTHAuthorization: BearerOAuth token authentication
# .env
MUTAGENT_API_KEY=mt_xxxxxxxxxxxx
import { Mutagent } from '@mutagent/sdk';

// No explicit auth needed -- env var is auto-read
const client = new Mutagent();

Timeout Configuration

const client = new Mutagent({
  timeoutMs: 60000, // 60 seconds
});

Retry Configuration

const client = new Mutagent({
  retryConfig: {
    strategy: 'backoff',
    backoff: {
      initialInterval: 500,
      maxInterval: 60000,
      exponent: 1.5,
      maxElapsedTime: 300000,
    },
    retryConnectionErrors: true,
  },
});

Per-Request Options

Override configuration for individual requests:
const prompts = await client.prompt.listPrompts(
  { limit: 50 },
  {
    timeoutMs: 120000,  // 2 minute timeout for this request
    retries: {
      strategy: 'none', // No retries for this request
    },
  }
);

Debug Logging

const client = new Mutagent({
  debugLogger: console, // Log all requests and responses
});

Custom HTTP Client

For advanced use cases (proxies, custom TLS, request interceptors), provide your own HTTP client:
import { Mutagent, HTTPClient } from '@mutagent/sdk';

const customClient: HTTPClient = {
  async request(input, init) {
    // Add custom headers, logging, etc.
    return fetch(input, init);
  },
};

const client = new Mutagent({
  httpClient: customClient,
});