Skip to main content
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",
});
​
userId
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",
});
​
collectionId
string
required
The parent collection ID.
​
userId
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",
});
​
collectionId
string
required
The parent collection under which to create the sub-collection.
​
collectionName
string
required
The name of the new collection.
​
userId
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,
});
​
collectionId
string
required
The collection ID.
​
userId
string
required
The Sublay user ID who owns the collection.
​
page
number
Page number (1-indexed). Defaults to 1.
​
limit
number
Results per page. Defaults to 20.
​
sortBy
string
Sort order: "new", "added" (when saved), "top", or "hot".
​
sortDir
string
Sort direction: "asc" or "desc".
​
include
string
Comma-separated list of associations to populate (e.g. "user").
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",
});
​
collectionId
string
required
The collection to add the entity to.
​
entityId
string
required
The Sublay entity ID to save.
​
userId
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",
});
​
collectionId
string
required
The collection to remove the entity from.
​
entityId
string
required
The Sublay entity ID to remove.
​
userId
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",
});
​
collectionId
string
required
The collection ID to update.
​
userId
string
required
The Sublay user ID who owns the collection.
​
name
string
The new collection name.
Returns — Promise<Collection>

​
deleteCollection

Deletes a collection. 
await sublay.collections.deleteCollection({
  collectionId: "col_xyz789",
  userId: "usr_abc123",
});
​
collectionId
string
required
The collection ID to delete.
​
userId
string
required
The Sublay user ID who owns the collection.
Returns — Promise<void>