> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sublay.io/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
export const SpaceReputationParams = ({variant = "context", field = "path"}) => {
const isUser = variant === "user";
return <>
Opt-in. Adds a spaceReputation number to each returned user,
scoped to a single space. Requires the reputation bundle.
The reputation total is always present regardless;{" "}
spaceReputation is purely additive and only appears when you
pass this object. This object is the primary form — it
replaces the deprecated flat props below. See the{" "}
Reputation data model for the
full contract.
{isUser ?
Which bucket to read. A space <uuid> reads that
space's bucket; "none" reads the
project-general (space-less) bucket.{" "}
"context" is rejected (400) on this
endpoint — there is no space context to derive. The empty string
and the legacy general / null aliases are
also rejected. Missing buckets read as 0.
:
Which bucket to read. One of: a space <uuid>{" "}
(that space's bucket), "none" (the
project-general, space-less bucket), or{" "}
"context" (the space derived from the
request context — resolved per-row on lists, or the single space on
member/team/conversation surfaces). The empty string and the legacy{" "}
general / null aliases are rejected (400).
Missing buckets read as 0.
}
Only honored when spaceId is an explicit space <uuid>.
When true, spaceReputation is the{" "}
subtree sum — the named space plus all of its
descendant spaces (the root space's own bucket included). Ignored for{" "}
"none"; not allowed with "context".
{isUser ? Deprecated — use the spaceReputation{" "}
object instead. The flat form of spaceReputation.spaceId.
Still accepted (the object wins if both are passed); removal is a later
major version. Accepts a space <uuid> or "none" only —{" "}
"context" is rejected (400) on this endpoint.
: Deprecated — use the spaceReputation{" "}
object instead. The flat form of spaceReputation.spaceId.
Still accepted (the object wins if both are passed); removal is a later
major version. Accepts a space <uuid>, "none", or{" "}
"context".
}
Deprecated — use{" "}
spaceReputation.includeDescendants instead. The flat form,
only honored alongside an explicit spaceReputationId<uuid>.
;
};
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`](/v8/js-sdk/follows) and [`connections`](/v8/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" });
```
The Sublay user ID.
Comma-separated list of associations to populate.
**Returns** — `Promise`
***
### fetchUserByForeignId
Fetches a user by your application's own user identifier.
```typescript theme={null}
const user = await sublay.users.fetchUserByForeignId({
foreignId: "external-user-42",
});
```
Your application's user identifier.
Comma-separated list of associations to populate.
**Returns** — `Promise`
***
### fetchUserByUsername
Fetches a user by their username.
```typescript theme={null}
const user = await sublay.users.fetchUserByUsername({ username: "alice" });
```
The user's unique username.
Comma-separated list of associations to populate.
**Returns** — `Promise`
***
### 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" });
```
Partial name or username to search for.
**Returns** — `Promise`
***
### checkUsernameAvailability
Checks whether a username is available.
```typescript theme={null}
const { available } = await sublay.users.checkUsernameAvailability({
username: "alice",
});
```
The username to check.
**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 },
});
```
The Sublay user ID to update. A user token may only update itself.
New display name.
New username. Must be available.
New avatar URL.
New bio text.
ISO 8601 date string for the user's birthdate.
Geographic location `{ latitude: number; longitude: number }`, or `null` to clear it.
Updated public metadata (`Record`).
Updated secure metadata (`Record`, not exposed in public responses).
A new avatar image to upload: `{ file: Blob | File; options: ImageOptions }`.
A new banner image to upload: `{ file: Blob | File; options: ImageOptions }`.
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.
```typescript theme={null}
// Uploading an avatar from an element
const input = document.querySelector("#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`
***
### fetchCommentsByUserId
Returns a user's comments — top-level comments and replies alike, across entities — cursor-paginated. See [Fetch Comments by User](/v8/api-reference/users/fetch-comments-by-user-id) for which comments the list contains.
```typescript theme={null}
const { data, pagination } = await sublay.users.fetchCommentsByUserId({
userId: "usr_abc123",
limit: 20,
include: ["entity"],
});
const next = await sublay.users.fetchCommentsByUserId({
userId: "usr_abc123",
limit: 20,
include: ["entity"],
cursor: pagination.nextCursor,
});
```
The Sublay user ID whose comments to fetch.
Only comments on this entity.
Only comments on entities with this `sourceId`.
How comments by users the viewer is [block-edged](/v8/sdk/moderation/overview#blocking) with are treated. `"exclude"` (default) leaves them out; `"include-outbound-blocked"` re-includes only the viewer's own outbound-blocked authors, marked `isAuthorBlocked: true`. No effect without the `moderation` bundle.
Comments per page. Server default `10`, max `100`.
`pagination.nextCursor` from the previous response, passed as returned. Omit it, or pass `null`, for the first page. Send the same sort as the request that returned it.
Server default `"createdAt"`. `"top"` ranks by the raw count of `sortByReaction`.
Applies to every sort. Server default `"desc"`.
With `sortBy: "top"` only. Server default `"upvote"`.
Related data to populate: `"user"`, `"entity"`, `"space"`, `"parent"`, `"grants"`.
**Returns** — `Promise>` — `{ data, pagination: { nextCursor, hasMore } }`
***
### 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,
});
```
The Sublay user ID whose followers to fetch.
Page number (1-indexed). Defaults to `1`.
Results per page. Defaults to `20`.
Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
**Returns** — `Promise>`
***
### fetchFollowersCountByUserId
Returns the total number of followers for the target user.
```typescript theme={null}
const { count } = await sublay.users.fetchFollowersCountByUserId({
userId: "usr_abc123",
});
```
The Sublay user ID.
**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,
});
```
The Sublay user ID whose following list to fetch.
Page number (1-indexed). Defaults to `1`.
Results per page. Defaults to `20`.
Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
**Returns** — `Promise>`
***
### fetchFollowingCountByUserId
Returns the number of users the target user is following.
```typescript theme={null}
const { count } = await sublay.users.fetchFollowingCountByUserId({
userId: "usr_abc123",
});
```
The Sublay user ID.
**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,
});
```
The Sublay user ID whose connections to fetch.
Page number (1-indexed). Defaults to `1`.
Results per page. Defaults to `20`.
Optional search term. Filters the list to connections whose connected user's username or name contains this text (case-insensitive). When omitted, no filtering is applied.
Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
**Returns** — `Promise>`
***
### fetchConnectionsCountByUserId
Returns the number of established connections for the target user.
```typescript theme={null}
const { count } = await sublay.users.fetchConnectionsCountByUserId({
userId: "usr_abc123",
});
```
The Sublay user ID.
**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" });
```
The user being followed (the target).
**Returns** — `Promise`
***
### deleteFollow
The logged-in user unfollows the target user.
```typescript theme={null}
await sublay.users.deleteFollow({ userId: "usr_target" });
```
The user being unfollowed (the target).
This unfollows by the target's `userId`. To delete one of your own follow
relationships by its record ID, use
[`follows.deleteFollow`](/v8/js-sdk/follows), which takes a `followId`.
**Returns** — `Promise`
***
### fetchFollowStatus
Returns whether the logged-in user follows the target user.
```typescript theme={null}
const { isFollowing, followId } = await sublay.users.fetchFollowStatus({
userId: "usr_target",
});
```
The user whose follow relationship is being checked (the target).
**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!",
});
```
The user the connection is requested with (the target).
Optional message to include with the request.
**Returns** — `Promise` — 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",
});
```
The other user in the connection (the target).
**Returns** — `Promise`
***
### 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",
});
```
The other user in the connection (the target).
**Returns** — `Promise`
## Blocking
User-to-user **blocking** is part of the trust & safety [moderation bundle](/v8/sdk/moderation/overview#blocking). These functions require that bundle; a project without it returns `403 database/tables-not-available`. The blocker is the **token holder** — there is no `actingUserId`.
Blocking severs interaction between two users across every Sublay surface and is **non-disclosing** — the blocked user is never notified. See [Moderation — Blocking](/v8/sdk/moderation/overview#blocking) for the full enforcement behavior.
***
### createBlock
Blocks a user. On a new block, existing follows and connections between the pair are torn down (both directions). Idempotent — re-blocking succeeds. Self-block is rejected server-side.
```typescript theme={null}
const block = await sublay.users.createBlock({ userId: "usr_target" });
```
The user being blocked (the target). The blocker is the token holder.
**Returns** — `Promise` — `{ id, blockerId, blockedId, createdAt }`.
***
### deleteBlock
Unblocks a user. Idempotent; restores nothing.
```typescript theme={null}
await sublay.users.deleteBlock({ userId: "usr_target" });
```
The user being unblocked (the target).
**Returns** — `Promise`
***
### fetchBlockStatus
Checks whether the token holder blocks the target user. **Outbound-only** — it never reveals whether the target has blocked the token holder.
```typescript theme={null}
const { blocked, blockId } = await sublay.users.fetchBlockStatus({
userId: "usr_target",
});
```
The user whose block relationship is being checked (the target).
**Returns** — `Promise` — `{ blocked: boolean; blockId?: string; createdAt?: string }`.
***
### fetchBlockedUsers
Returns a paginated list of the users the token holder has blocked (their outbound blocks), each row carrying a public profile summary. This block list is **private** to the blocker.
```typescript theme={null}
const { data, pagination } = await sublay.users.fetchBlockedUsers({
page: 1,
limit: 20,
});
```
Page number (1-indexed). Defaults to `1`.
Results per page. Defaults to `20`. Max `100`.
**Returns** — `Promise>`, where each `BlockedUserListItem` is `{ id, blockedUser, createdAt }`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.