> ## 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,
  },
});
```