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 and connections modules instead.

---

fetchUserById

Fetches a user by their internal Sublay user ID.

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

userId · string · required

The Sublay user ID.

include · string

Comma-separated list of associations to populate.

spaceReputationId · 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.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<User>

---

fetchUserByForeignId

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

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

foreignId · string · required

Your application’s user identifier.

include · string

Comma-separated list of associations to populate.

spaceReputationId · 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.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<User>

---

fetchUserByUsername

Fetches a user by their username.

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

username · string · required

The user’s unique username.

include · string

Comma-separated list of associations to populate.

spaceReputationId · 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.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<User>

---

fetchUserSuggestions

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

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

query · string · required

Partial name or username to search for.

spaceReputationId · 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.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<User[]>

---

checkUsernameAvailability

Checks whether a username is available.

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

username · string · required

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.

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

userId · string · required

The Sublay user ID to update. A user token may only update itself.

name · string

New display name.

username · string

New username. Must be available.

avatar · string

New avatar URL.

bio · string

New bio text.

birthdate · string

ISO 8601 date string for the user’s birthdate.

location · object

Geographic location { latitude: number; longitude: number }, or null to clear it.

metadata · object

Updated public metadata (Record<string, any>).

secureMetadata · object

Updated secure metadata (Record<string, any>, not exposed in public responses).

avatarFile · object

A new avatar image to upload: { file: Blob | File; options: ImageOptions }.

bannerFile · object

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.

// 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.

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

userId · string · required

The Sublay user ID whose followers to fetch.

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Defaults to 20.

spaceReputationId · 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.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<PaginatedResponse<FollowListItem>>

---

fetchFollowersCountByUserId

Returns the total number of followers for the target user.

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

userId · string · required

The Sublay user ID.

Returns — Promise<{ count: number }>

---

fetchFollowingByUserId

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

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

userId · string · required

The Sublay user ID whose following list to fetch.

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Defaults to 20.

spaceReputationId · 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.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<PaginatedResponse<FollowListItem>>

---

fetchFollowingCountByUserId

Returns the number of users the target user is following.

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

userId · string · required

The Sublay user ID.

Returns — Promise<{ count: number }>

---

fetchConnectionsByUserId

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

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

userId · string · required

The Sublay user ID whose connections to fetch.

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Defaults to 20.

spaceReputationId · 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.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<PaginatedResponse<EstablishedConnection>>

---

fetchConnectionsCountByUserId

Returns the number of established connections for the target user.

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

userId · string · required

The Sublay user ID.

Returns — Promise<{ count: number }>

---

createFollow

The logged-in user follows the target user.

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

userId · string · required

The user being followed (the target).

Returns — Promise<Follow>

---

deleteFollow

The logged-in user unfollows the target user.

await sublay.users.deleteFollow({ userId: "usr_target" });

userId · string · required

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, which takes a followId.

Returns — Promise<void>

---

fetchFollowStatus

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

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

userId · string · required

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.

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

userId · string · required

The user the connection is requested with (the target).

message · string

Optional message to include with the request.

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

---

fetchConnectionStatus

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

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

userId · string · required

The other user in the connection (the target).

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.

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

userId · string · required

The other user in the connection (the target).

Returns — Promise<RemoveConnectionByUserIdResponse>