Users

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

string

required

The Sublay user ID.

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

string

required

Your application’s user identifier.

boolean

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

string

Display name — used only when creating a new user.

string

Username — used only when creating a new user.

string

Avatar URL — used only when creating a new user.

string

Bio text — used only when creating a new user.

object

Public metadata — used only when creating a new user.

object

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

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

string

required

The user’s unique username.

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

string

required

The Sublay user ID to update.

string

New display name.

string

New username. Must be available.

string

New bio text.

string

New avatar URL.

object

Updated public metadata. Merged with existing metadata.

object

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

string

ISO 8601 date string for the user’s birthdate.

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

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

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

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

string

required

The Sublay user ID.

number

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

number

Results per page. Defaults to 20.

string

Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.

string

Restricts which field query matches against — username or name. When omitted, query matches either field.

Returns — Promise<PaginatedResponse<User>>

fetchFollowersCountByUserId

Returns the total number of followers for a user.

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

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

string

required

The Sublay user ID.

number

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

number

Results per page. Defaults to 20.

string

Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.

string

Restricts which field query matches against — username or name. When omitted, query matches either field.

Returns — Promise<PaginatedResponse<User>>

fetchFollowingCountByUserId

Returns the number of users the specified user is following.

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

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

string

required

The Sublay user ID.

number

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

number

Results per page. Defaults to 20.

string

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.

string

Restricts which field query matches against — username or name. When omitted, query matches either field.

Returns — Promise<PaginatedResponse<EstablishedConnection>>

fetchConnectionsCountByUserId

Returns the number of established connections for a user.

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

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

string

required

The user being followed (the target).

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

string

required

The user being unfollowed (the target).

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

string

required

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

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

string

required

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

string

required

The user sending the request (the requester).

string

Optional message to include with the request.

Returns — Promise<ConnectionRequestResponse> — the created/pending 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"

string

required

The other user in the connection (the target).

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"

string

required

The other user in the connection (the target).

string

required

The user withdrawing, declining, or disconnecting.

Returns — Promise<RemoveConnectionByUserIdResponse>

Acting on a user’s blocks

User-to-user blocking is part of the trust & safety moderation bundle. 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 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.

const block = await sublay.users.createBlock({
  userId: "usr_target",
  actingUserId: "usr_blocker",
});

string

required

The user being blocked (the target).

string

required

The user performing the block (the blocker).

Returns — Promise<Block> — { id, blockerId, blockedId, createdAt }.

deleteBlock

Removes a block on behalf of the blocker. Idempotent; restores nothing.

await sublay.users.deleteBlock({
  userId: "usr_target",
  actingUserId: "usr_blocker",
});

string

required

The user being unblocked (the target).

string

required

The user performing the unblock (the blocker).

Returns — Promise<void>

fetchBlockStatus

Checks whether the acting user blocks the target user. Outbound-only — it never reveals whether the target has blocked the acting user.

const { blocked, blockId } = await sublay.users.fetchBlockStatus({
  userId: "usr_target",
  actingUserId: "usr_blocker",
});

string

required

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

string

required

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.

const { data, pagination } = await sublay.users.fetchBlockedUsers({
  actingUserId: "usr_blocker",
  page: 1,
  limit: 20,
});

string

required

The user whose own block list to read (the blocker).

number

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

number

Results per page. Defaults to 20. Max 100.

Returns — Promise<PaginatedResponse<BlockedUser>>, where each BlockedUser is { id, blockedUser, createdAt }.

Getting Started

Modules

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

Acting on a user’s blocks

createBlock

deleteBlock

fetchBlockStatus

fetchBlockedUsers

​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

​Acting on a user’s blocks

​createBlock

​deleteBlock

​fetchBlockStatus

​fetchBlockedUsers

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

Acting on a user’s blocks

createBlock

deleteBlock

fetchBlockStatus

fetchBlockedUsers