# API Reference (/docs/api)



## `createClient(options?)` [#createclientoptions]

Returns an `ApiClient`. See [Client options](/docs/client-options).

## Requests [#requests]

| Method                          | Returns            |
| ------------------------------- | ------------------ |
| `get<R>(url, config?)`          | `Promise<IRes<R>>` |
| `post<R>(url, body?, config?)`  | `Promise<IRes<R>>` |
| `put<R>(url, body?, config?)`   | `Promise<IRes<R>>` |
| `patch<R>(url, body?, config?)` | `Promise<IRes<R>>` |
| `delete<R>(url, config?)`       | `Promise<IRes<R>>` |

## Auth [#auth]

| Method                                                   | Does                                                                       |
| -------------------------------------------------------- | -------------------------------------------------------------------------- |
| `login(body, config?)`                                   | POST to `loginUrl` and store the returned tokens                           |
| `logout(config?)`                                        | POST to `logoutUrl`, clear tokens in every tab                             |
| `setTokens({ accessToken?, refreshToken?, expiresAt? })` | Store tokens you got elsewhere. A key set to `undefined` clears that token |
| `refresh()`                                              | Refresh now. Resolves `true` if the session is usable                      |
| `getAuthState()`                                         | `{ isAuthenticated, expiresAt, user }`. Never includes tokens              |
| `onAuthStateChange(listener)`                            | Subscribe. Returns an unsubscribe function                                 |
| `restoreSession(url?)`                                   | Cookie mode: ask the server whether a session exists                       |
| `getSocketToken(url, options?)`                          | Fetch a socket ticket from your server. See [WebSockets](/docs/websockets) |
| `getAccessToken()`                                       | The access token. Requires `exposeTokens: true`                            |

## Cancellation [#cancellation]

| Method                       | Does                                                      |
| ---------------------------- | --------------------------------------------------------- |
| `cancel(selector?, reason?)` | Cancel matching requests and return how many were stopped |
| `pending(selector?)`         | List matching in-flight requests                          |
| `cancelScope(name?)`         | A client whose requests can all be canceled together      |

A selector is a key, group or URL pattern (`"/users/:id"`, `"/api/**/images"`), a `RegExp`, an object `{ url, method, key, group }` or a function.

## Other [#other]

| Member      | Does                                                             |
| ----------- | ---------------------------------------------------------------- |
| `isWorker`  | `true` when requests run in a Web Worker                         |
| `destroy()` | Stop the worker and tab channel. Call it for short-lived clients |

## `IRes<R>` [#iresr]

```ts
interface IRes<R> {
  data?: R;                                // payload, unwrapped from { data }
  body?: unknown;                          // whole body when data was unwrapped
  status: boolean;                         // true for 2xx
  statusCode: number;                      // 0 = network error or canceled
  message: string;
  errors?: Record<string, string[]>;       // validation errors from the server
  headers?: Record<string, string>;
  canceled?: boolean;
  cancelReason?: string;
  error?: unknown;
  loading: boolean;                        // always false once settled
}
```

## `ApiError` [#apierror]

Thrown on failure while `throwError` is on. Has `statusCode`, `message`, `errors`, `data`, `canceled` and the full `response` envelope.

## Other exports [#other-exports]

| Export                                         | Does                                                   |
| ---------------------------------------------- | ------------------------------------------------------ |
| `buildQueryString(params)`                     | The query-string serializer the client uses            |
| `getTokenExpiry(token)`                        | Expiry of a JWT in epoch ms, or `null`                 |
| `isTokenExpired(token, skewMs?)`               | Whether a JWT has expired, or will within `skewMs`     |
| `detectBaseUrl()`                              | The `baseUrl` the client would pick from env variables |
| `MemoryStorage`, `WebStorage`, `CookieStorage` | The built-in storage adapters                          |
| `services` (from `@mrzr/api-client/services`)  | See [Plugins](/docs/plugins)                           |

All types (`ClientOptions`, `RequestConfig`, `IRes`, `AuthState`, `ApiPlugin`, …) are exported too.