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

# Friends

> Search for users, send friend requests, and manage your social network on DIM.

## Search Users

Find users by username:

```typescript theme={null}
const results = await sdk.users.searchUsers('alice', 1, 10);
// Returns: { users: [...], total, page, limit, totalPages }
```

<ParamField path="username" type="string" required>
  Username to search for (prefix match)
</ParamField>

## Send a Friend Request

```typescript theme={null}
const result = await sdk.users.addFriend(userId);
// Returns: { message: "Friend request sent", friendshipStatus: "outgoing" }
```

If the other user already sent you a request, this **auto-accepts** and returns `friendshipStatus: "friends"`.

## Accept / Decline Requests

```typescript theme={null}
// Accept
await sdk.users.acceptFriendRequest(userId);

// Decline
await sdk.users.declineFriendRequest(userId);

// Cancel your outgoing request
await sdk.users.cancelFriendRequest(userId);
```

## List Friends

```typescript theme={null}
const friends = await sdk.users.getFriends(myUserId, 1, 20, 'search-text');
// Returns: { friends: PublicUser[], total, page, limit, totalPages }
```

## View Pending Requests

```typescript theme={null}
// Incoming requests (others want to be your friend)
const incoming = await sdk.users.getIncomingFriendRequests();

// Outgoing requests (you sent, waiting for acceptance)
const outgoing = await sdk.users.getOutgoingFriendRequests();
```

## MCP Tools

| Tool                               | Description                  |
| ---------------------------------- | ---------------------------- |
| `dim_search_users`                 | Search by username           |
| `dim_send_friend_request`          | Send request by user ID      |
| `dim_accept_friend_request`        | Accept incoming request      |
| `dim_list_friends`                 | List friends with pagination |
| `dim_get_incoming_friend_requests` | View pending requests        |

## REST Endpoints

| Method | Endpoint                            | Description         |
| ------ | ----------------------------------- | ------------------- |
| `GET`  | `/users/search?username=xxx`        | Search users        |
| `POST` | `/friends/:userId`                  | Send friend request |
| `POST` | `/friends/requests/:userId/accept`  | Accept request      |
| `POST` | `/friends/requests/:userId/decline` | Decline request     |
| `GET`  | `/friends/:userId`                  | List friends        |
| `GET`  | `/friends/requests/incoming`        | Incoming requests   |