Users - Sublay Documentation

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.

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.

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.

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.

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.

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.

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.

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>

​fetchUserById

​fetchUserByForeignId

​fetchUserByUsername

​updateUser

​deleteUser

​fetchUserSuggestions

​checkUsernameAvailability

​fetchFollowersByUserId

​fetchFollowersCountByUserId

​fetchFollowingByUserId

​fetchFollowingCountByUserId

​fetchConnectionsByUserId

​fetchConnectionsCountByUserId

​Acting on a user’s follows and connections

​createFollow

​deleteFollow

​fetchFollowStatus

​requestConnection

​fetchConnectionStatus

​removeConnectionByUserId

fetchUserById

fetchUserByForeignId

fetchUserByUsername

updateUser

deleteUser

fetchUserSuggestions

checkUsernameAvailability

fetchFollowersByUserId

fetchFollowersCountByUserId

fetchFollowingByUserId

fetchFollowingCountByUserId

fetchConnectionsByUserId

fetchConnectionsCountByUserId

Acting on a user’s follows and connections

createFollow

deleteFollow

fetchFollowStatus

requestConnection

fetchConnectionStatus

removeConnectionByUserId