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

# RecallrAI Client

> Main client class for interacting with RecallrAI

## Overview

The `RecallrAI` client is the entry point for all SDK operations. It manages authentication and provides methods for user management.

## Initialization

```typescript theme={null}
import { RecallrAI } from "recallrai";

const client = new RecallrAI({
  apiKey: "rai_yourapikey",
  projectId: "project-uuid",
  baseUrl: "https://api.recallrai.com",
  timeout: 60,
});
```

## Methods

### createUser()

```typescript theme={null}
import { UserAlreadyExistsError } from "recallrai";

try {
  const user = await client.createUser("user123", { name: "John Doe", role: "admin" });
  console.log(`Created user: ${user.userId}`);
} catch (error) {
  if (error instanceof UserAlreadyExistsError) {
    console.log(`Error: ${error.message}`);
  }
}
```

<ParamField path="userId" type="string" required>
  Unique identifier for the user. Must be unique within your project.
</ParamField>

<ParamField path="metadata" type="object">
  Optional metadata to associate with the user.
</ParamField>

**Returns:** `User`

**Raises:** `UserAlreadyExistsError`

***

### getUser()

```typescript theme={null}
import { UserNotFoundError } from "recallrai";

try {
  const user = await client.getUser("user123");
  console.log(`User metadata:`, user.metadata);
} catch (error) {
  if (error instanceof UserNotFoundError) {
    console.log(`Error: ${error.message}`);
  }
}
```

<ParamField path="userId" type="string" required>
  The ID of the user to retrieve.
</ParamField>

<ParamField path="options.validate" type="boolean" default="true">
  Whether to validate user existence via API before creating the instance. Set `false` only when `userId` is already trusted.
</ParamField>

**Returns:** `User`

**Raises:** `UserNotFoundError`

<Tip>
  Set `{ validate: false }` to skip the SDK lookup request (`GET /api/v1/users/{userId}`) when the user ID is already trusted by your system.
</Tip>

<Note>
  When `{ validate: false }` is used, fields that require an API lookup (for example `createdAt`, `lastActiveAt`, and `metadata`) are set to `UNAVAILABLE` until you call `refresh()`.
  Import `UNAVAILABLE` from `recallrai` when checking these values.
</Note>

***

### listUsers()

```typescript theme={null}
const userList = await client.listUsers({
  offset: 0,
  limit: 10,
  metadataFilter: { role: "admin" },
});

console.log(`Total users: ${userList.total}`);
console.log(`Has more: ${userList.hasMore}`);
```

<ParamField path="offset" type="number">
  Number of users to skip. Default: `0`
</ParamField>

<ParamField path="limit" type="number">
  Maximum number of users to return. Default: `10`
</ParamField>

<ParamField path="metadataFilter" type="object">
  Filter users by metadata fields.
</ParamField>

**Returns:** `UserList` with `users`, `total`, and `hasMore`.