Users

Fetch, update and delete user profiles, check usernames, and query follow and connection graphs

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.

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 profile by your application’s own user identifier. Optionally creates the user if not found.

const user = await sublay.users.fetchUserByForeignId({
  foreignId: "external-user-42",
  createIfNotFound: true,
  name: "Bob Smith",
  username: "bob",
});

foreignId · string · required

Your application’s user identifier.

createIfNotFound · boolean

When true, creates the user with the provided profile fields if no match is found. Defaults to false.

name · string

Display name — used only when creating a new user.

username · string

Username — used only when creating a new user.

avatar · string

Avatar URL — used only when creating a new user.

bio · string

Bio text — used only when creating a new user.

metadata · object

Public metadata — used only when creating a new user.

secureMetadata · object

Secure metadata (not exposed to the client) — used only when creating a new user.

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 profile 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>

---

updateUser

Updates a user’s profile fields.

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 },
});

userId · string · required

The Sublay user ID to update.

name · string

New display name.

username · string

New username. Must be available.

bio · string

New bio text.

avatar · string

New avatar URL.

metadata · object

Updated public metadata. Merged with existing metadata.

secureMetadata · object

Updated secure metadata (not exposed in public responses). Merged with existing values.

birthdate · string

ISO 8601 date string for the user’s birthdate.

location · object

Geographic location { latitude: number; longitude: number }.

Returns — Promise<UserFull>

---

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.

await sublay.users.deleteUser({ userId: "usr_abc123" });

userId · string · required

The Sublay user ID to delete.

Returns — Promise<void>

---

fetchUserSuggestions

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

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 for registration.

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

username · string · required

The username to check.

Returns — Promise<{ available: boolean }>

---

fetchFollowersByUserId

Returns a paginated list of users following the specified user.

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

userId · string · required

The Sublay user ID.

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<User>>

---

fetchFollowersCountByUserId

Returns the total number of followers for a 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 specified user is following.

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

userId · string · required

The Sublay user ID.

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<User>>

---

fetchFollowingCountByUserId

Returns the number of users the specified 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 established mutual connections for a user.

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

userId · string · required

The Sublay user ID.

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 a user.

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

userId · string · required

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

---

createFollow

Makes one user follow another.

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

userId · string · required

The user being followed (the target).

actingUserId · string · required

The user performing the follow (the follower).

Returns — Promise<Follow>

---

deleteFollow

Makes one user unfollow another.

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

userId · string · required

The user being unfollowed (the target).

actingUserId · string · required

The user performing the unfollow (the follower).

Returns — Promise<void>

---

fetchFollowStatus

Checks whether the acting user follows the target user.

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

userId · string · required

The user whose follow relationship is being checked (the target).

actingUserId · string · required

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.

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

userId · string · required

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

actingUserId · string · required

The user sending the request (the requester).

message · string

Optional message to include with the request.

Returns — Promise<Connection>

---

fetchConnectionStatus

Returns the connection status between the acting user and the target user.

const status = await sublay.users.fetchConnectionStatus({
  userId: "usr_target",
  actingUserId: "usr_viewer",
});
// status.status is "none" | "pending" | "connected" | "declined"

userId · string · required

The other user in the connection (the target).

actingUserId · string · required

The user whose perspective the status is from.

Returns — Promise<ConnectionStatusResponse> — 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.

const result = await sublay.users.removeConnectionByUserId({
  userId: "usr_target",
  actingUserId: "usr_viewer",
});
// result.action is "withdraw" | "disconnect" | "decline"

userId · string · required

The other user in the connection (the target).

actingUserId · string · required

The user withdrawing, declining, or disconnecting.

Returns — Promise<RemoveConnectionByUserIdResponse>