> ## 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, update and delete user profiles, check usernames, and query follow and connection graphs
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 provides server-side access to user profiles, social graph data (follows and connections), and username availability. All operations use your project API key and do not require a user access token.
***
### fetchUserById
Fetches a user profile 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 profile by your application's own user identifier. Optionally creates the user if not found.
```typescript theme={null}
const user = await sublay.users.fetchUserByForeignId({
foreignId: "external-user-42",
createIfNotFound: true,
name: "Bob Smith",
username: "bob",
});
```
Your application's user identifier.
When `true`, creates the user with the provided profile fields if no match is found. Defaults to `false`.
Display name — used only when creating a new user.
Username — used only when creating a new user.
Avatar URL — used only when creating a new user.
Bio text — used only when creating a new user.
Public metadata — used only when creating a new user.
Secure metadata (not exposed to the client) — used only when creating a new user.
Comma-separated list of associations to populate.
**Returns** — `Promise`
***
### fetchUserByUsername
Fetches a user profile 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`
***
### updateUser
Updates a user's profile fields.
```typescript theme={null}
const updatedUser = await sublay.users.updateUser({
userId: "usr_abc123",
name: "Alice Updated",
bio: "New bio",
avatar: "https://cdn.example.com/avatar.jpg",
location: { latitude: 37.7749, longitude: -122.4194 },
});
```
The Sublay user ID to update.
New display name.
New username. Must be available.
New bio text.
New avatar URL.
Updated public metadata. Merged with existing metadata.
Updated secure metadata (not exposed in public responses). Merged with existing values.
ISO 8601 date string for the user's birthdate.
Geographic location `{ latitude: number; longitude: number }`.
**Returns** — `Promise`
***
### deleteUser
Permanently deletes a user and cascades cleanup across all of their related data — reactions, files, follows, connections, notifications, collections, reports, and mentions are removed, and their entities and comments are stripped of authored content. This mirrors the full-cascade delete performed from the dashboard.
This is a hard, irreversible delete — the user and their related data cannot be recovered.
```typescript theme={null}
await sublay.users.deleteUser({ userId: "usr_abc123" });
```
The Sublay user ID to delete.
**Returns** — `Promise`
***
### fetchUserSuggestions
Returns users whose name or username matches a partial query string. Useful for mention autocomplete on the server.
```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 for registration.
```typescript theme={null}
const { available } = await sublay.users.checkUsernameAvailability({
username: "alice",
});
```
The username to check.
**Returns** — `Promise<{ available: boolean }>`
***
### 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).
Pass `actingUserId` to read the history as that user: their own moderator-removed comments are included in full, the block rules and `blockedFilter` apply from their perspective (comments on an entity whose author blocked them are left out, except [their own](/v8/api-reference/users/fetch-comments-by-user-id#your-own-comments-on-an-unavailable-entity)), the `isAuthorBlocked` / `isUnavailable` flags are set and `userReaction` is populated. Without it the read is anonymous: deleted and moderator-removed comments are left out, no block rule applies, `isAuthorBlocked` and `isUnavailable` are always `false`, and `userReaction` isn't populated.
```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.
The user to read the history as. Omit for the anonymous view.
Only comments on this entity.
Only comments on entities with this `sourceId`.
How comments by users `actingUserId` is block-edged with are treated: `"exclude"` (default) leaves them out; `"include-outbound-blocked"` re-includes comments by users they blocked, marked `isAuthorBlocked: true`. No effect without `actingUserId`.
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 specified user.
```typescript theme={null}
const { data, pagination } = await sublay.users.fetchFollowersByUserId({
userId: "usr_abc123",
page: 1,
limit: 20,
});
```
The Sublay user ID.
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 a 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 specified user is following.
```typescript theme={null}
const { data, pagination } = await sublay.users.fetchFollowingByUserId({
userId: "usr_abc123",
page: 1,
limit: 20,
});
```
The Sublay user ID.
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 specified 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 established mutual connections for a user.
```typescript theme={null}
const { data, pagination } = await sublay.users.fetchConnectionsByUserId({
userId: "usr_abc123",
page: 1,
limit: 20,
});
```
The Sublay user ID.
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 a user.
```typescript theme={null}
const { count } = await sublay.users.fetchConnectionsCountByUserId({
userId: "usr_abc123",
});
```
The Sublay user ID.
**Returns** — `Promise<{ count: number }>`
***
## Acting on a user's follows and connections
The functions above are read-only queries about a target user. The functions below **perform an action** on behalf of one user toward another. Because a service key isn't tied to a single user, these routes take both:
* `userId` — the **target** of the action (the user being followed, connected with, etc.), taken from the request path.
* `actingUserId` — the **actor** performing it (the follower, the requester, the user whose perspective a status is from).
Listing and managing the acting user's own follow/connection graph by record ID
lives on the dedicated [`follows`](/v8/node-sdk/follows) and
[`connections`](/v8/node-sdk/connections) modules.
***
### createFollow
Makes one user follow another.
```typescript theme={null}
const follow = await sublay.users.createFollow({
userId: "usr_target",
actingUserId: "usr_follower",
});
```
The user being followed (the target).
The user performing the follow (the follower).
**Returns** — `Promise`
***
### deleteFollow
Makes one user unfollow another.
```typescript theme={null}
await sublay.users.deleteFollow({
userId: "usr_target",
actingUserId: "usr_follower",
});
```
The user being unfollowed (the target).
The user performing the unfollow (the follower).
**Returns** — `Promise`
***
### fetchFollowStatus
Checks whether the acting user follows the target user.
```typescript theme={null}
const { isFollowing, followId } = await sublay.users.fetchFollowStatus({
userId: "usr_target",
actingUserId: "usr_viewer",
});
```
The user whose follow relationship is being checked (the target).
The user whose perspective the status is from.
**Returns** — `Promise<{ isFollowing: boolean; followId?: string }>`
***
### requestConnection
Sends a connection request from the acting user to the target user.
```typescript theme={null}
const connection = await sublay.users.requestConnection({
userId: "usr_target",
actingUserId: "usr_requester",
message: "Let's connect!",
});
```
The user the connection is requested with (the target).
The user sending the request (the requester).
Optional message to include with the request.
**Returns** — `Promise` — the created/pending connection.
***
### fetchConnectionStatus
Returns the connection status between the acting user and the target user.
```typescript theme={null}
const status = await sublay.users.fetchConnectionStatus({
userId: "usr_target",
actingUserId: "usr_viewer",
});
// status.status is "none" | "pending" | "connected" | "declined"
```
The other user in the connection (the target).
The user whose perspective the status is from.
**Returns** — `Promise` — a discriminated union on `status`: `"none"`, `"pending"` (with `type` and `connectionId`), `"connected"`, or `"declined"`.
***
### removeConnectionByUserId
Removes the connection between the acting user and 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",
actingUserId: "usr_viewer",
});
// result.action is "withdraw" | "disconnect" | "decline"
```
The other user in the connection (the target).
The user withdrawing, declining, or disconnecting.
**Returns** — `Promise`
## Acting on a user's blocks
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`. Each acts on behalf of one user (the blocker) — pass that user's ID as `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 one user on behalf of another. On a new block, existing follows and connections between the pair are torn down (both directions) in one transaction. Idempotent — re-blocking succeeds. Self-block is rejected.
```typescript theme={null}
const block = await sublay.users.createBlock({
userId: "usr_target",
actingUserId: "usr_blocker",
});
```
The user being blocked (the target).
The user performing the block (the blocker).
**Returns** — `Promise` — `{ id, blockerId, blockedId, createdAt }`.
***
### deleteBlock
Removes a block on behalf of the blocker. Idempotent; restores nothing.
```typescript theme={null}
await sublay.users.deleteBlock({
userId: "usr_target",
actingUserId: "usr_blocker",
});
```
The user being unblocked (the target).
The user performing the unblock (the blocker).
**Returns** — `Promise`
***
### fetchBlockStatus
Checks whether the acting user blocks the target user. **Outbound-only** — it never reveals whether the target has blocked the acting user.
```typescript theme={null}
const { blocked, blockId } = await sublay.users.fetchBlockStatus({
userId: "usr_target",
actingUserId: "usr_blocker",
});
```
The user whose block relationship is being checked (the target).
The user whose outbound perspective the status is from (the blocker).
**Returns** — `Promise<{ blocked: boolean; blockId?: string; createdAt?: string }>`
***
### fetchBlockedUsers
Returns a paginated list of the users the acting user 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({
actingUserId: "usr_blocker",
page: 1,
limit: 20,
});
```
The user whose own block list to read (the blocker).
Page number (1-indexed). Defaults to `1`.
Results per page. Defaults to `20`. Max `100`.
**Returns** — `Promise>`, where each `BlockedUser` is `{ id, blockedUser, createdAt }`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.