Collections

The collections module manages a user’s saved-content collections. Every user has a single root collection, under which they can nest sub-collections and into which they can save entities.

Collections are always scoped to a specific user. Pass that user’s Sublay ID as userId on every call — your service key performs the operation on behalf of that named user.

fetchRootCollection

Fetches a user’s root collection, creating it on first access if it does not yet exist.

const root = await sublay.collections.fetchRootCollection({
  userId: "usr_abc123",
});

string

required

The Sublay user ID whose root collection to fetch.

Returns — Promise<Collection>

fetchSubCollections

Fetches the direct child collections nested under a given collection.

const subCollections = await sublay.collections.fetchSubCollections({
  collectionId: "col_root123",
  userId: "usr_abc123",
});

string

required

The parent collection ID.

string

required

The Sublay user ID who owns the collection.

Returns — Promise<Collection[]>

createNewCollection

Creates a new sub-collection under an existing parent collection.

const collection = await sublay.collections.createNewCollection({
  collectionId: "col_root123",
  collectionName: "Recipes",
  userId: "usr_abc123",
});

string

required

The parent collection under which to create the sub-collection.

string

required

The name of the new collection.

string

required

The Sublay user ID who will own the collection.

Returns — Promise<Collection>

fetchCollectionEntities

Fetches a paginated list of entities saved in a collection.

const { data, pagination } = await sublay.collections.fetchCollectionEntities({
  collectionId: "col_xyz789",
  userId: "usr_abc123",
  sortBy: "added",
  page: 1,
  limit: 20,
});

string

required

The collection ID.

string

required

The Sublay user ID who owns the collection.

number

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

number

Results per page. Defaults to 20.

string

Sort order: "new" (creation date), "added" (when saved), "top" (reaction count), or "hot" (engagement score).

string

Which reaction top ranks by: "upvote", "downvote", "like", "love", "wow", "sad", "angry", or "funny". Defaults to "upvote". Only valid with sortBy: "top" — the server rejects it with any other sort.

string

Sort direction: "asc" or "desc".

CollectionEntityIncludeParam

Associations to populate: "user", "space", "topComments", "files", "grants" (a single value or an array). "saved" isn’t accepted — every returned entity already has isSaved: true. On an entity whose author has blocked the user, topComments is [].

number

With include containing "topComments": how many top comments per entity. Server default 1, maximum 5. Rejected (400) without "topComments" in include.

ReactionType

With include containing "topComments": the reaction whose raw count ranks the top comments. Server default "upvote". Rejected (400) without "topComments" in include.

Returns — Promise<PaginatedResponse<Entity>>

addEntityToCollection

Saves an entity into a collection.

const collection = await sublay.collections.addEntityToCollection({
  collectionId: "col_xyz789",
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});

string

required

The collection to add the entity to.

string

required

The Sublay entity ID to save.

string

required

The Sublay user ID who owns the collection.

Returns — Promise<Collection>

removeEntityFromCollection

Removes an entity from a collection.

await sublay.collections.removeEntityFromCollection({
  collectionId: "col_xyz789",
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});

string

required

The collection to remove the entity from.

string

required

The Sublay entity ID to remove.

string

required

The Sublay user ID who owns the collection.

Returns — Promise<void>

updateCollection

Renames a collection.

const collection = await sublay.collections.updateCollection({
  collectionId: "col_xyz789",
  userId: "usr_abc123",
  name: "Favorite Recipes",
});

string

required

The collection ID to update.

string

required

The Sublay user ID who owns the collection.

string

required

The new collection name. Must be a non-empty string.

Returns — Promise<Collection>

deleteCollection

Deletes a collection.

await sublay.collections.deleteCollection({
  collectionId: "col_xyz789",
  userId: "usr_abc123",
});

string

required

The collection ID to delete.

string

required

The Sublay user ID who owns the collection.

Returns — Promise<void>

Getting Started

Modules

fetchRootCollection

fetchSubCollections

createNewCollection

fetchCollectionEntities

addEntityToCollection

removeEntityFromCollection

updateCollection

deleteCollection

​fetchRootCollection

​fetchSubCollections

​createNewCollection

​fetchCollectionEntities

​addEntityToCollection

​removeEntityFromCollection

​updateCollection

​deleteCollection

fetchRootCollection

fetchSubCollections

createNewCollection

fetchCollectionEntities

addEntityToCollection

removeEntityFromCollection

updateCollection

deleteCollection