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
actingUserId, the user your service key acts as, on every call.fetchRootCollection
Fetches a user’s root collection, creating it on first access if it does not yet exist.string
required
The user the service key acts as, whose root collection to fetch.
Promise<Collection>
fetchSubCollections
Fetches the direct child collections nested under a given collection.string
required
The parent collection ID.
string
required
The user the service key acts as, who owns the collection.
Promise<Collection[]>
createNewCollection
Creates a new sub-collection under an existing parent collection.string
required
The parent collection under which to create the sub-collection.
string
required
The name of the new collection. Trimmed; 1 to 255 characters after trimming.
string
required
The user the service key acts as, who will own the collection.
Promise<Collection>
fetchCollectionEntities
Fetches a paginated list of entities saved in a collection.string
required
The collection ID.
string
required
The user the service key acts as, who owns the collection.
number
Page number (1-indexed). Defaults to
1.number
Results per page. Defaults to
20.string
Sort order:
"createdAt" (creation date), "addedAt" (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". Not accepted with "hot", which ranks one way only.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.Promise<PaginatedResponse<Entity>>
addEntityToCollection
Saves an entity into a collection.string
required
The collection to add the entity to.
string
required
The Sublay entity ID to save.
string
required
The user the service key acts as, who owns the collection.
Promise<Collection>
removeEntityFromCollection
Removes an entity from a collection.string
required
The collection to remove the entity from.
string
required
The Sublay entity ID to remove.
string
required
The user the service key acts as, who owns the collection.
Promise<void>
updateCollection
Renames a collection.string
required
The collection ID to update.
string
required
The user the service key acts as, who owns the collection.
string
required
The new collection name. Must be a non-empty string.
Promise<Collection>
deleteCollection
Deletes a collection.string
required
The collection ID to delete.
string
required
The user the service key acts as, who owns the collection.
Promise<void>
