> ## Documentation Index
> Fetch the complete documentation index at: https://replyke-feat-push-rich-payload-fields.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Users

> Fetch and update user profiles, check usernames, and act on a specific user's follow and connection graph

The `users` module reads and updates user profiles and lets the logged-in user act on the social graph of an **arbitrary target user**, addressed by `userId`.

In the follow and connection helpers below, `userId` is always the **target** — the user being followed, the other party in a connection, or the user whose followers you're reading. The **actor** is always the logged-in token holder. To act on your own graph (your own followers, the users you follow, your own connections and pending requests), use the [`follows`](/v7/js-sdk/follows) and [`connections`](/v7/js-sdk/connections) modules instead.

***

### fetchUserById

Fetches a user by their internal Sublay user ID.

```typescript theme={null}
const user = await sublay.users.fetchUserById({ userId: "usr_abc123" });
```

<ParamField body="userId" type="string" required>
  The Sublay user ID.
</ParamField>

<ParamField body="include" type="string">
  Comma-separated list of associations to populate.
</ParamField>

<ParamField body="spaceReputationId" type="string">
  Opts the returned user into a `spaceReputation` number. Accepts a space `<uuid>` or `"none"` (the project-general bucket) only — `"context"` is rejected (400), since a bare user lookup has no space context. The empty string and the legacy `general` / `null` aliases are also rejected. See [Reputation](/data-models/reputation).
</ParamField>

<ParamField body="spaceReputationDescendants" type="boolean">
  Only honored alongside an explicit space `<uuid>`. When `true`, `spaceReputation` is the subtree sum — the named space plus all of its descendants.
</ParamField>

**Returns** — `Promise<User>`

***

### fetchUserByForeignId

Fetches a user by your application's own user identifier.

```typescript theme={null}
const user = await sublay.users.fetchUserByForeignId({
  foreignId: "external-user-42",
});
```

<ParamField body="foreignId" type="string" required>
  Your application's user identifier.
</ParamField>

<ParamField body="include" type="string">
  Comma-separated list of associations to populate.
</ParamField>

<ParamField body="spaceReputationId" type="string">
  Opts the returned user into a `spaceReputation` number. Accepts a space `<uuid>` or `"none"` (the project-general bucket) only — `"context"` is rejected (400), since a bare user lookup has no space context. The empty string and the legacy `general` / `null` aliases are also rejected. See [Reputation](/data-models/reputation).
</ParamField>

<ParamField body="spaceReputationDescendants" type="boolean">
  Only honored alongside an explicit space `<uuid>`. When `true`, `spaceReputation` is the subtree sum — the named space plus all of its descendants.
</ParamField>

**Returns** — `Promise<User>`

***

### fetchUserByUsername

Fetches a user by their username.

```typescript theme={null}
const user = await sublay.users.fetchUserByUsername({ username: "alice" });
```

<ParamField body="username" type="string" required>
  The user's unique username.
</ParamField>

<ParamField body="include" type="string">
  Comma-separated list of associations to populate.
</ParamField>

<ParamField body="spaceReputationId" type="string">
  Opts the returned user into a `spaceReputation` number. Accepts a space `<uuid>` or `"none"` (the project-general bucket) only — `"context"` is rejected (400), since a bare user lookup has no space context. The empty string and the legacy `general` / `null` aliases are also rejected. See [Reputation](/data-models/reputation).
</ParamField>

<ParamField body="spaceReputationDescendants" type="boolean">
  Only honored alongside an explicit space `<uuid>`. When `true`, `spaceReputation` is the subtree sum — the named space plus all of its descendants.
</ParamField>

**Returns** — `Promise<User>`

***

### fetchUserSuggestions

Returns users whose name or username matches a partial query string. Useful for mention autocomplete.

```typescript theme={null}
const users = await sublay.users.fetchUserSuggestions({ query: "ali" });
```

<ParamField body="query" type="string" required>
  Partial name or username to search for.
</ParamField>

<ParamField body="spaceReputationId" type="string">
  Opts each returned user into a `spaceReputation` number. Accepts a space `<uuid>` or `"none"` (the project-general bucket) only — `"context"` is rejected (400), since this lookup has no space context. The empty string and the legacy `general` / `null` aliases are also rejected. See [Reputation](/data-models/reputation).
</ParamField>

<ParamField body="spaceReputationDescendants" type="boolean">
  Only honored alongside an explicit space `<uuid>`. When `true`, `spaceReputation` is the subtree sum — the named space plus all of its descendants.
</ParamField>

**Returns** — `Promise<User[]>`

***

### checkUsernameAvailability

Checks whether a username is available.

```typescript theme={null}
const { available } = await sublay.users.checkUsernameAvailability({
  username: "alice",
});
```

<ParamField body="username" type="string" required>
  The username to check.
</ParamField>

**Returns** — `Promise<{ available: boolean }>`

***

### updateUser

Updates a user's profile, optionally uploading a new avatar and/or banner image. A user token may only update its own profile.

```typescript theme={null}
const updatedUser = await sublay.users.updateUser({
  userId: "usr_abc123",
  name: "Alice Updated",
  bio: "New bio",
  location: { latitude: 37.7749, longitude: -122.4194 },
});
```

<ParamField body="userId" type="string" required>
  The Sublay user ID to update. A user token may only update itself.
</ParamField>

<ParamField body="name" type="string">
  New display name.
</ParamField>

<ParamField body="username" type="string">
  New username. Must be available.
</ParamField>

<ParamField body="avatar" type="string">
  New avatar URL.
</ParamField>

<ParamField body="bio" type="string">
  New bio text.
</ParamField>

<ParamField body="birthdate" type="string">
  ISO 8601 date string for the user's birthdate.
</ParamField>

<ParamField body="location" type="object">
  Geographic location `{ latitude: number; longitude: number }`, or `null` to clear it.
</ParamField>

<ParamField body="metadata" type="object">
  Updated public metadata (`Record<string, any>`).
</ParamField>

<ParamField body="secureMetadata" type="object">
  Updated secure metadata (`Record<string, any>`, not exposed in public responses).
</ParamField>

<ParamField body="avatarFile" type="object">
  A new avatar image to upload: `{ file: Blob | File; options: ImageOptions }`.
</ParamField>

<ParamField body="bannerFile" type="object">
  A new banner image to upload: `{ file: Blob | File; options: ImageOptions }`.
</ParamField>

<Note>
  When `avatarFile` or `bannerFile` is supplied the request is sent as
  `multipart/form-data` carrying the browser `File`/`Blob`. The image `options`
  (an `ImageOptions` object whose `mode` selects a processing strategy) are sent
  alongside the file.
</Note>

```typescript theme={null}
// Uploading an avatar from an <input type="file"> element
const input = document.querySelector<HTMLInputElement>("#avatar-input");
const file = input.files[0];

const updatedUser = await sublay.users.updateUser({
  userId: "usr_abc123",
  avatarFile: {
    file,
    options: {
      mode: "exact-dimensions",
      dimensions: { default: { width: 256, height: 256 } },
      format: "webp",
    },
  },
});
```

**Returns** — `Promise<AuthUser>`

***

### fetchFollowersByUserId

Returns a paginated list of users following the target user.

```typescript theme={null}
const { data, pagination } = await sublay.users.fetchFollowersByUserId({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField body="userId" type="string" required>
  The Sublay user ID whose followers to fetch.
</ParamField>

<ParamField body="page" type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField body="limit" type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField body="spaceReputationId" type="string">
  Opts each returned follower into a `spaceReputation` number. Accepts a space `<uuid>` or `"none"` (the project-general bucket) only — `"context"` is rejected (400), since this list has no space context. The empty string and the legacy `general` / `null` aliases are also rejected. See [Reputation](/data-models/reputation).
</ParamField>

<ParamField body="spaceReputationDescendants" type="boolean">
  Only honored alongside an explicit space `<uuid>`. When `true`, `spaceReputation` is the subtree sum — the named space plus all of its descendants.
</ParamField>

**Returns** — `Promise<PaginatedResponse<FollowListItem>>`

***

### fetchFollowersCountByUserId

Returns the total number of followers for the target user.

```typescript theme={null}
const { count } = await sublay.users.fetchFollowersCountByUserId({
  userId: "usr_abc123",
});
```

<ParamField body="userId" type="string" required>
  The Sublay user ID.
</ParamField>

**Returns** — `Promise<{ count: number }>`

***

### fetchFollowingByUserId

Returns a paginated list of users that the target user is following.

```typescript theme={null}
const { data, pagination } = await sublay.users.fetchFollowingByUserId({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField body="userId" type="string" required>
  The Sublay user ID whose following list to fetch.
</ParamField>

<ParamField body="page" type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField body="limit" type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField body="spaceReputationId" type="string">
  Opts each returned user into a `spaceReputation` number. Accepts a space `<uuid>` or `"none"` (the project-general bucket) only — `"context"` is rejected (400), since this list has no space context. The empty string and the legacy `general` / `null` aliases are also rejected. See [Reputation](/data-models/reputation).
</ParamField>

<ParamField body="spaceReputationDescendants" type="boolean">
  Only honored alongside an explicit space `<uuid>`. When `true`, `spaceReputation` is the subtree sum — the named space plus all of its descendants.
</ParamField>

**Returns** — `Promise<PaginatedResponse<FollowListItem>>`

***

### fetchFollowingCountByUserId

Returns the number of users the target user is following.

```typescript theme={null}
const { count } = await sublay.users.fetchFollowingCountByUserId({
  userId: "usr_abc123",
});
```

<ParamField body="userId" type="string" required>
  The Sublay user ID.
</ParamField>

**Returns** — `Promise<{ count: number }>`

***

### fetchConnectionsByUserId

Returns a paginated list of the target user's established connections.

```typescript theme={null}
const { data, pagination } = await sublay.users.fetchConnectionsByUserId({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField body="userId" type="string" required>
  The Sublay user ID whose connections to fetch.
</ParamField>

<ParamField body="page" type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField body="limit" type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField body="spaceReputationId" type="string">
  Opts each returned connection's user into a `spaceReputation` number. Accepts a space `<uuid>` or `"none"` (the project-general bucket) only — `"context"` is rejected (400), since this list has no space context. The empty string and the legacy `general` / `null` aliases are also rejected. See [Reputation](/data-models/reputation).
</ParamField>

<ParamField body="spaceReputationDescendants" type="boolean">
  Only honored alongside an explicit space `<uuid>`. When `true`, `spaceReputation` is the subtree sum — the named space plus all of its descendants.
</ParamField>

**Returns** — `Promise<PaginatedResponse<EstablishedConnection>>`

***

### fetchConnectionsCountByUserId

Returns the number of established connections for the target user.

```typescript theme={null}
const { count } = await sublay.users.fetchConnectionsCountByUserId({
  userId: "usr_abc123",
});
```

<ParamField body="userId" type="string" required>
  The Sublay user ID.
</ParamField>

**Returns** — `Promise<{ count: number }>`

***

### createFollow

The logged-in user follows the target user.

```typescript theme={null}
const follow = await sublay.users.createFollow({ userId: "usr_target" });
```

<ParamField body="userId" type="string" required>
  The user being followed (the target).
</ParamField>

**Returns** — `Promise<Follow>`

***

### deleteFollow

The logged-in user unfollows the target user.

```typescript theme={null}
await sublay.users.deleteFollow({ userId: "usr_target" });
```

<ParamField body="userId" type="string" required>
  The user being unfollowed (the target).
</ParamField>

<Note>
  This unfollows by the target's `userId`. To delete one of your own follow
  relationships by its record ID, use
  [`follows.deleteFollow`](/v7/js-sdk/follows), which takes a `followId`.
</Note>

**Returns** — `Promise<void>`

***

### fetchFollowStatus

Returns whether the logged-in user follows the target user.

```typescript theme={null}
const { isFollowing, followId } = await sublay.users.fetchFollowStatus({
  userId: "usr_target",
});
```

<ParamField body="userId" type="string" required>
  The user whose follow relationship is being checked (the target).
</ParamField>

**Returns** — `Promise<{ isFollowing: boolean; followId?: string; followedAt?: string }>`

***

### requestConnection

Sends a connection request from the logged-in user to the target user.

```typescript theme={null}
const connection = await sublay.users.requestConnection({
  userId: "usr_target",
  message: "Let's connect!",
});
```

<ParamField body="userId" type="string" required>
  The user the connection is requested with (the target).
</ParamField>

<ParamField body="message" type="string">
  Optional message to include with the request.
</ParamField>

**Returns** — `Promise<ConnectionRequestResponse>` — the created/pending connection.

***

### fetchConnectionStatus

Returns the connection status between the logged-in user and the target user.

```typescript theme={null}
const status = await sublay.users.fetchConnectionStatus({
  userId: "usr_target",
});
```

<ParamField body="userId" type="string" required>
  The other user in the connection (the target).
</ParamField>

**Returns** — `Promise<ConnectionStatusResponse>`

***

### removeConnectionByUserId

Removes the connection with the target user — withdrawing a sent request, declining a received one, or disconnecting an established connection, depending on the current state.

```typescript theme={null}
const result = await sublay.users.removeConnectionByUserId({
  userId: "usr_target",
});
```

<ParamField body="userId" type="string" required>
  The other user in the connection (the target).
</ParamField>

**Returns** — `Promise<RemoveConnectionByUserIdResponse>`