Connections

Query and respond to a user’s mutual connections from your server

The connections module reads and manages a user’s mutual connections (bidirectional relationships, similar to “friends”). Use it to list established connections, inspect pending requests, and accept, decline, or remove connections.

Every function acts on behalf of a named user. Pass that user’s Sublay ID as userId — your service key performs the operation as that user.

To send a connection request, check a connection’s status, or remove a connection by the other user’s ID, use the nested routes on the users module (requestConnection, fetchConnectionStatus, removeConnectionByUserId), which take an actingUserId.

---

fetchConnections

Fetches a paginated list of a user’s established (mutual) connections.

const { data, pagination } = await sublay.connections.fetchConnections({
  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.

Returns — Promise<PaginatedResponse<EstablishedConnection>>

---

fetchConnectionsCount

Returns the number of established connections for a user.

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

userId · string · required

The Sublay user ID.

Returns — Promise<{ count: number }>

---

fetchSentPendingConnections

Returns a paginated list of connection requests the user has sent that are still pending.

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

userId · string · required

The Sublay user ID whose sent requests to fetch.

page · number

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

limit · number

Results per page. Defaults to 20.

Returns — Promise<PaginatedResponse<PendingConnection>>

---

fetchReceivedPendingConnections

Returns a paginated list of pending connection requests the user has received.

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

userId · string · required

The Sublay user ID whose received requests to fetch.

page · number

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

limit · number

Results per page. Defaults to 20.

Returns — Promise<PaginatedResponse<PendingConnection>>

---

acceptConnection

Accepts a pending connection request received by the user.

const result = await sublay.connections.acceptConnection({
  connectionId: "con_xyz789",
  userId: "usr_abc123",
});

connectionId · string · required

The ID of the pending connection request to accept.

userId · string · required

The Sublay user ID accepting the request (the recipient).

Returns — Promise<ConnectionActionResponse> — { id, status, createdAt?, respondedAt? }

---

declineConnection

Declines a pending connection request received by the user.

const result = await sublay.connections.declineConnection({
  connectionId: "con_xyz789",
  userId: "usr_abc123",
});

connectionId · string · required

The ID of the pending connection request to decline.

userId · string · required

The Sublay user ID declining the request (the recipient).

Returns — Promise<ConnectionActionResponse> — { id, status, createdAt?, respondedAt? }

---

removeConnection

Removes an established connection (or withdraws a pending request) by its connection ID.

await sublay.connections.removeConnection({
  connectionId: "con_xyz789",
  userId: "usr_abc123",
});

connectionId · string · required

The connection ID to remove.

userId · string · required

The Sublay user ID on whose behalf the connection is removed.

Returns — Promise<void>