Node.js SDK - Sublay Documentation

The @sublay/node SDK gives you full programmatic access to the Sublay API from any Node.js environment. It is designed for server-side use only — backend endpoints, Next.js server actions, webhook handlers, cron jobs, and scripts.

This SDK requires a secret API key and must never be used in client-side code or shipped to the browser.

Installation

npm install @sublay/node

Initialization

Create a single SublayClient instance at startup and reuse it throughout your application.

import { SublayClient } from "@sublay/node";

const sublay = await SublayClient.init({
  projectId: process.env.SUBLAY_PROJECT_ID!,
  apiKey: process.env.SUBLAY_API_KEY!,
});

Configuration

projectId

string

required

Your Sublay project ID, found in the dashboard under Settings → General.

apiKey

string

required

Your secret API key from the dashboard. Keep this in an environment variable — never commit it to source control.

isInternal

boolean

Set to true when making internal/admin requests that bypass standard project authorization. Defaults to false.

Modules

Once initialized, all functionality is accessed through module namespaces on the client:

sublay.auth              // Authentication — sign up, sign in, tokens, passwords
sublay.users             // User profiles, follow/connection actions
sublay.entities          // Content entities — CRUD, reactions, drafts
sublay.comments          // Comments — CRUD, reactions
sublay.collections       // Saved-content collections
sublay.follows           // Follow graph — followers, following, counts
sublay.connections       // Mutual connections and requests
sublay.spaces            // Spaces — management, members, moderation, rules
sublay.events            // Events — RSVPs, hosts, invites, guest list
sublay.chat              // Conversations, messages, members, reactions, read state
sublay.search            // Search and AI Q&A
sublay.reports           // Content reports and the moderation queue
sublay.appNotifications  // In-app notification feed
sublay.storage           // File and image uploads, read, delete

Acting on behalf of a user

Your service key authenticates as the project, not as any single end user. So functions that operate on a user’s behalf take an explicit userId — the named user the action is performed as (saving to a collection, reading a notification feed, filing a report, listing connections). A few routes — on the users module (following someone, requesting a connection) and on chat (createDirectConversation, addMember, removeMember, changeMemberRole) — act on one user toward another. There the target is userId and the actor is passed separately as actingUserId.

oauth is intentionally not exposed by this SDK (it’s a browser redirect flow).

Auth

Users

Fetch, update and delete profiles, follow and connection actions

Entities

Create and manage content, reactions, drafts

Comments

Create and manage comments, reactions

Collections

Organize a user’s saved entities into collections

Follows

Read a user’s follow graph and counts

Connections

Mutual connections, pending requests, accept/decline

Spaces

Space CRUD, navigation, slug management

Space Members

Membership, roles, approvals, bans

Space Moderation

Reports, content moderation, rules, digest

Chat

Conversations, messages, members, reactions, read state

Search

Full-text search and AI-powered Q&A

Reports

File content reports and read the moderation queue

App Notifications

Read and mark a user’s in-app notifications

Storage

Upload, fetch, and delete files and images

Paginated Responses

Functions that return lists use a shared PaginatedResponse<T> shape:

{
  data: T[];
  pagination: {
    page: number;
    pageSize: number;
    totalPages: number;
    totalItems: number;
    hasMore: boolean;
  };
}

Pass page and limit to any list function to control pagination.

​Installation

​Initialization

​Configuration

​Modules

​Acting on behalf of a user

Auth

Users

Entities

Comments

Collections

Follows

Connections

Spaces

Space Members

Space Moderation

Chat

Search

Reports

App Notifications

Storage

​Paginated Responses

Installation

Initialization

Configuration

Modules

Acting on behalf of a user

Paginated Responses