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

# ApiClient

> The core HTTP client class in ByteKit — typed requests, interceptors, retries, circuit breaker, and response validation.

## Import

```ts theme={null}
import { ApiClient, ApiError, createApiClient } from "bytekit/api-client";
```

## What it does

`ApiClient` is the main request abstraction in ByteKit. It wraps the Fetch API with timeouts, request/response interceptors, automatic retries, circuit breaker protection, localized error messages, and optional response validation through built-in schemas or external libraries like Zod and Valibot.

## Constructor

```ts theme={null}
const api = new ApiClient(config: ApiClientConfig);
```

### `ApiClientConfig`

| Property              | Type                                     | Default            | Description                                                                                                                                 |
| --------------------- | ---------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl`             | `string \| URL`                          | —                  | **Required.** Base URL for all requests. Alias: `baseURL`.                                                                                  |
| `defaultHeaders`      | `HeadersInit`                            | `{}`               | Headers sent with every request.                                                                                                            |
| `timeoutMs`           | `number`                                 | `15000`            | Request timeout in milliseconds.                                                                                                            |
| `locale`              | `"en" \| "es"`                           | `"es"`             | Locale for built-in error messages.                                                                                                         |
| `interceptors`        | `ApiClientInterceptors`                  | —                  | Request and response interceptor functions.                                                                                                 |
| `disableInterceptors` | `boolean`                                | `false`            | Disable all interceptors.                                                                                                                   |
| `logger`              | `Logger`                                 | —                  | Logger instance for request/error logging.                                                                                                  |
| `retryPolicy`         | `RetryConfig`                            | —                  | Retry configuration (see [RetryPolicy](/api-reference/retry-policy)).                                                                       |
| `circuitBreaker`      | `CircuitBreakerConfig`                   | —                  | Circuit breaker configuration (see [CircuitBreaker](/api-reference/circuit-breaker)).                                                       |
| `fetchImpl`           | `typeof fetch`                           | `globalThis.fetch` | Custom fetch implementation.                                                                                                                |
| `errorMessages`       | `Record<Locale, Record<number, string>>` | Built-in           | Override default error messages per status code and locale.                                                                                 |
| `logHeaders`          | `boolean`                                | `false`            | Include headers in log output.                                                                                                              |
| `logSensitiveData`    | `boolean`                                | `false`            | Allow raw request/response payload logging. Disabled by default since v3 to prevent secrets leaking into logs. Do not enable in production. |
| `redactHeaderKeys`    | `string[]`                               | Auth/cookie keys   | Header keys to redact from logs.                                                                                                            |

## Basic setup

```ts theme={null}
const api = new ApiClient({
  baseUrl: "https://api.example.com",
  timeoutMs: 10_000,
  defaultHeaders: {
    Authorization: `Bearer ${token}`,
  },
});
```

## Methods

### HTTP verbs

| Method    | Signature                                                   | Description                                                |
| --------- | ----------------------------------------------------------- | ---------------------------------------------------------- |
| `get`     | `get<T>(path, options?): Promise<T>`                        | GET request.                                               |
| `post`    | `post<T>(path, bodyOrOptions?): Promise<T>`                 | POST request. Accepts a body directly or `RequestOptions`. |
| `put`     | `put<T>(path, bodyOrOptions?): Promise<T>`                  | PUT request. Same flexibility as `post`.                   |
| `patch`   | `patch<T>(path, bodyOrOptions?): Promise<T>`                | PATCH request. Same flexibility as `post`.                 |
| `delete`  | `delete<T>(path, options?): Promise<T>`                     | DELETE request.                                            |
| `getList` | `getList<T>(path, options?): Promise<PaginatedResponse<T>>` | GET with built-in pagination, sorting, and filters.        |

<Tip>
  `post`, `put`, and `patch` accept either a plain body object or a full `RequestOptions` object with a `body` property — whichever is more convenient.
</Tip>

### `RequestOptions<T>`

| Property           | Type                                            | Description                                                                     |
| ------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------- |
| `searchParams`     | `Record<string, QueryParam>`                    | Query string parameters.                                                        |
| `headers`          | `HeadersInit`                                   | Per-request headers (merged with defaults).                                     |
| `timeoutMs`        | `number`                                        | Override the client-level timeout.                                              |
| `validateResponse` | `ValidationSchema \| SchemaAdapter<T>`          | Validate the response body.                                                     |
| `signal`           | `AbortSignal`                                   | Cancellation signal.                                                            |
| `skipRetry`        | `boolean`                                       | Skip retry policy for this request.                                             |
| `skipInterceptors` | `boolean`                                       | Skip interceptors for this request.                                             |
| `body`             | `FormData \| string \| Record<string, unknown>` | Request body (when using options form).                                         |
| `logSensitiveData` | `boolean`                                       | Allow raw payload logging for this request. Overrides the client-level setting. |

### `ListOptions<T>`

Extends `RequestOptions` with pagination, sorting, and filter helpers.

| Property     | Type                         | Description                                 |
| ------------ | ---------------------------- | ------------------------------------------- |
| `pagination` | `{ page?, limit?, offset? }` | Pagination parameters.                      |
| `sort`       | `{ field?, order? }`         | Sort field and direction.                   |
| `filters`    | `Record<string, QueryParam>` | Filter parameters merged into query string. |

## Examples

### Typed GET

```ts theme={null}
type User = { id: number; name: string };

const user = await api.get<User>("/users/1");
```

### POST with payload

```ts theme={null}
const created = await api.post<{ id: string }>("/users", {
  name: "Ada Lovelace",
});
```

### POST with full options

```ts theme={null}
const created = await api.post<{ id: string }>("/users", {
  body: { name: "Ada Lovelace" },
  headers: { "X-Idempotency-Key": crypto.randomUUID() },
});
```

### Paginated list

```ts theme={null}
const result = await api.getList<Product>("/products", {
  pagination: { page: 1, limit: 20 },
  sort: { field: "price", order: "desc" },
  filters: { category: "electronics" },
});

console.log(result.data);             // Product[]
console.log(result.pagination.total);  // total count
```

### Response validation with Zod

```ts theme={null}
import { zodAdapter } from "bytekit/schema-adapter";
import { z } from "zod";

const UserSchema = z.object({ id: z.number(), name: z.string() });

const user = await api.get("/users/1", {
  validateResponse: zodAdapter(UserSchema),
});
```

## Interceptors

Interceptors let you transform requests before they are sent and responses before they are returned.

```ts theme={null}
const api = new ApiClient({
  baseUrl: "https://api.example.com",
  interceptors: {
    request: async (url, init) => {
      const headers = new Headers(init.headers);
      headers.set("X-Trace-Id", crypto.randomUUID());
      return [url, { ...init, headers }];
    },
    response: async (response) => {
      // Log slow responses
      return response;
    },
  },
});
```

## `ApiError`

Thrown when a response has a non-2xx status code.

| Property     | Type      | Description                                    |
| ------------ | --------- | ---------------------------------------------- |
| `status`     | `number`  | HTTP status code.                              |
| `statusText` | `string`  | HTTP status text.                              |
| `message`    | `string`  | Localized error message.                       |
| `body`       | `unknown` | Parsed response body, if available.            |
| `isTimeout`  | `boolean` | `true` when the error was caused by a timeout. |

```ts theme={null}
try {
  await api.get("/protected");
} catch (err) {
  if (err instanceof ApiError) {
    console.error(err.status, err.message);
  }
}
```

`ApiError` also exposes a `details` getter, `toJSON()`, and a readable `toString()` for debugging.

<Warning>
  **v3:** `ApiError#toJSON()`, `ApiError#toString()`, and `ApiError#details` now sanitize the response body by default. Sensitive fields (tokens, passwords, cookies, API keys, etc.) are redacted and long strings are truncated. If you need the raw body, read `error.body` directly in controlled code — do not log or serialize it in production.
</Warning>

## Factory

`createApiClient` is a shortcut for `new ApiClient(config)`.

```ts theme={null}
import { createApiClient } from "bytekit/api-client";

const api = createApiClient({
  baseUrl: "https://api.example.com",
});
```

<Note>
  `ApiClient` requires either `baseUrl` or `baseURL` in the config. An error is thrown at construction time if neither is provided.
</Note>