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

# Configuration

> Configure the StructClient with auth, timeouts, retries, and hooks.

All constructors accept a single `StructClientConfig` object:

```typescript theme={null}
import { StructClient } from "@structbuild/sdk";

const client = new StructClient({
  apiKey: "sk_live_xxx",
  timeout: 10_000,
  retry: {
    maxRetries: 3,
    initialDelayMs: 500,
    maxDelayMs: 30_000,
  },
  headers: {
    "X-App-Version": "1.4.0",
  },
  onRequest: ({ method, url }) => console.log(`${method} ${url}`),
  onResponse: ({ status, durationMs }) => console.log(`${status} in ${durationMs}ms`),
});
```

## Options

| Option | Type | Default | Description |
| - | - | - | - |
| `apiKey` | `string` | required | Secret (`sk_*`) or JWT public key (`pk_jwt_*`). Sent as `X-API-Key`. |
| `jwt` | `string` | (none) | User JWT, sent as `Authorization: Bearer`. Only used with `pk_jwt_*` keys. |
| `baseUrl` | `string` | `https://api.struct.to/v1` | Override the REST base URL. |
| `headers` | `Record<string, string>` | (none) | Extra headers merged into every request. |
| `timeout` | `number` | `30_000` | Per-request timeout in milliseconds. Enforced with `AbortController`. |
| `retry` | `RetryConfig` | off | Automatic retry on `429` and `5xx`. Disabled when omitted. |
| `onRequest` | `(info) => void \| Promise<void>` | (none) | Called before every request. |
| `onResponse` | `(info) => void \| Promise<void>` | (none) | Called after every response. |

## Retry

Pass a `retry` block to enable exponential backoff on retryable failures (`429`, `500`, `502`, `503`, `504`, `NetworkError`, `TimeoutError`). `Retry-After` headers on `429` responses are honoured when present.

```typescript theme={null}
const client = new StructClient({
  apiKey: "sk_live_xxx",
  retry: {
    maxRetries: 3,
    initialDelayMs: 500,
    maxDelayMs: 10_000,
  },
});
```

| Field | Default | Description |
| - | - | - |
| `maxRetries` | `3` | Maximum retry attempts after the initial request. |
| `initialDelayMs` | `1000` | Base delay, doubled on each attempt. |
| `maxDelayMs` | `30_000` | Upper bound on the computed delay. |

## Hooks

`onRequest` and `onResponse` fire around every HTTP call and are useful for logging, tracing, and metrics. Hook errors are swallowed so they never break a request.

```typescript theme={null}
const client = new StructClient({
  apiKey: "sk_live_xxx",
  onRequest: ({ method, url, headers }) => {
    tracer.start({ method, url });
  },
  onResponse: ({ method, url, status, durationMs, headers }) => {
    tracer.end({ method, url, status, durationMs });
  },
});
```

## Custom base URL

Enterprise customers with a dedicated domain can point the SDK at their own host by overriding `baseUrl`. Include the `/v1` prefix; the SDK does not add it for you.

```typescript theme={null}
const client = new StructClient({
  apiKey: "sk_live_xxx",
  baseUrl: "https://api.yourcompany.com/v1",
});
```

## WebSocket configuration

`StructWebSocket` and `StructAlertsWebSocket` share a similar config shape, plus reconnect and subscribe-timeout options. See [WebSockets](/sdk/websockets) for details.

```typescript theme={null}
import { StructWebSocket } from "@structbuild/sdk";

const ws = new StructWebSocket({
  apiKey: "sk_live_xxx",
  baseUrl: "wss://api.yourcompany.com",
  subscribeTimeout: 10_000,
  reconnect: {
    maxRetries: 10,
    initialDelayMs: 500,
    maxDelayMs: 30_000,
  },
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.