Collections

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

fetchRootCollection

Fetches the logged-in user’s root collection.

const root = await sublay.collections.fetchRootCollection();

Returns — Promise<Collection>

fetchSubCollections

Fetches the immediate sub-collections of a collection.

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

string

required

The parent collection ID.

Returns — Promise<Collection[]>

createNewCollection

Creates a sub-collection under a parent collection.

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

string

required

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

string

required

The name of the new collection.

Returns — Promise<Collection>

fetchCollectionEntities

Fetches the entities within a collection, paginated.

const { data, pagination } = await sublay.collections.fetchCollectionEntities({
  collectionId: "col_abc123",
  sortBy: "added",
  sortDir: "desc",
});

string

required

The collection ID.

number

The page number to fetch.

number

The number of entities to return per page.

"new" | "added" | "top" | "hot"

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.

"asc" | "desc"

Sort direction.

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

Adds an entity to a collection.

const result = await sublay.collections.addEntityToCollection({
  collectionId: "col_abc123",
  entityId: "ent_222",
});

string

required

The collection ID.

string

required

The ID of the entity to add.

Returns — Promise<{ success: boolean; collection: { id: string; entityCount: number } }>

removeEntityFromCollection

Removes an entity from a collection.

const result = await sublay.collections.removeEntityFromCollection({
  collectionId: "col_abc123",
  entityId: "ent_222",
});

string

required

The collection ID.

string

required

The ID of the entity to remove.

Returns — Promise<{ success: boolean; collection: { id: string; entityCount: number } }>

updateCollection

Renames a collection.

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

string

required

The collection ID.

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

string

required

The collection ID.

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