Collections

Organize a user’s saved entities into a tree of collections from your server

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>