Bookmarks

Overview

The API includes built-in support for bookmarking activities. Here's a quick example of how to use the bookmark API.

Adding Bookmarks

// Adding a bookmark to a new folder
val bookmark: Result<BookmarkData> = feed.addBookmark(activityId = "activity_123")

// Adding to an existing folder
val bookmarkWithFolder: Result<BookmarkData> = feed.addBookmark(
    activityId = "activity_123",
    request = AddBookmarkRequest(folderId = "folder_456")
)

// Update a bookmark (without a folder initially) - add custom data and move it to a new folder
val updatedBookmark: Result<BookmarkData> = feed.updateBookmark(
    activityId = "activity_123",
    request = UpdateBookmarkRequest(
        custom = mapOf("color" to "blue"),
        newFolder = AddFolderRequest(
            custom = mapOf("icon" to "📁"),
            name = "New folder name"
        )
    )
)

// Update a bookmark - move it from one existing folder to another existing folder
val movedBookmark: Result<BookmarkData> = feed.updateBookmark(
    activityId = "activity_123",
    request = UpdateBookmarkRequest(
        folderId = "folder_456",
        newFolderId = "folder_789"
    )
)

Removing Bookmarks

// Removing a bookmark
feed.deleteBookmark(
    activityId = "activity_123",
    folderId = "folder_456"
)

// When you read a feed we include the bookmark
feed.getOrCreate()
feed.state.activities.collect { activities ->
    println(activities.first().ownBookmarks)
}

Querying Bookmarks

// Query bookmarks
val query = BookmarksQuery(limit = 5)
val bookmarkList = client.bookmarkList(query = query)
val page1: Result<List<BookmarkData>> = bookmarkList.get()

// Get next page
val page2: Result<List<BookmarkData>> = bookmarkList.queryMoreBookmarks(limit = 3)

// Query by activity ID
val activityBookmarkList = client.bookmarkList(
    query = BookmarksQuery(
        filter = BookmarksFilterField.activityId.equal("activity_123")
    )
)
val activityBookmarks: Result<List<BookmarkData>> = activityBookmarkList.get()

// Query by folder ID
val folderBookmarkList = client.bookmarkList(
    query = BookmarksQuery(
        filter = BookmarksFilterField.folderId.equal("folder_456")
    )
)
val folderBookmarks: Result<List<BookmarkData>> = folderBookmarkList.get()

Bookmarks Queryable Built-In Fields

name type description supported operations example
user_id string or list of strings The ID of the user who owns the bookmark $in, $eq { user_id: { $eq: 'user_123' } }
activity_id string or list of strings The ID of the activity that was bookmarked $in, $eq { activity_id: { $eq: 'activity_123' } }
folder_id string or list of strings The ID of the folder containing the bookmark $eq, $in, $exists { folder_id: { $exists: true } }
created_at string, must be formatted as an RFC3339 timestamp The time the bookmark was created $eq, $gt, $gte, $lt, $lte { created_at: { $gte: '2023-12-04T09:30:20.45Z' } }
updated_at string, must be formatted as an RFC3339 timestamp The time the bookmark was last updated $eq, $gt, $gte, $lt, $lte { updated_at: { $gte: '2023-12-04T09:30:20.45Z' } }

Querying Bookmark Folders

// Query bookmark folders
val query = BookmarkFoldersQuery(limit = 5)
val bookmarkFolderList = client.bookmarkFolderList(query = query)
val page1: Result<List<BookmarkFolderData>> = bookmarkFolderList.get()

// Get next page
val page2: Result<List<BookmarkFolderData>> = bookmarkFolderList.queryMoreBookmarkFolders(limit = 3)

// Query by folder name (partial matching)
val projectFolderList = client.bookmarkFolderList(
    query = BookmarkFoldersQuery(
        filter = BookmarkFoldersFilterField.folderName.contains("project")
    )
)
val projectFolders: Result<List<BookmarkFolderData>> = projectFolderList.get()

Bookmark Folders Queryable Built-In Fields

name type description supported operations example
user_id string or list of strings The ID of the user who owns the folder $in, $eq { user_id: { $eq: 'user_123' } }
folder_name string or list of strings The name of the bookmark folder $eq, $in, $contains { folder_name: { $contains: 'work' } }
created_at string, must be formatted as an RFC3339 timestamp The time the folder was created $eq, $gt, $gte, $lt, $lte { created_at: { $gte: '2023-12-04T09:30:20.45Z' } }
updated_at string, must be formatted as an RFC3339 timestamp The time the folder was last updated $eq, $gt, $gte, $lt, $lte { updated_at: { $gte: '2023-12-04T09:30:20.45Z' } }

Managing Bookmark Folders

Update bookmark folder

The endpoint performs a partial update: only the fields you include in the request are changed, and each of those fields is completely overwritten.

Updating a bookmark folder sends feeds.bookmark_folder.updated event to the clients of the user who owns the folder. There are no default client-side SDK handlers for this event, but you can add a custom handler if your UI needs to be updated.

Delete bookmark folder

Use the delete bookmark folder endpoint to remove a folder by ID. All bookmarks in that folder are removed.

Deleting a bookmark folder sends feeds.bookmark_folder.deleted event to the clients of the user who owns the folder. There are no default client-side SDK handlers for this event, but you can add a custom handler if your UI needs to be updated.

// Add a bookmark with a new folder
val bookmark = feed.addBookmark(
    activityId = activity.id,
    request = AddBookmarkRequest(newFolder = AddFolderRequest(name = "Breakfast recipes", custom = mapOf("icon" to "🍳")))
)

// Update the folder
val updatedFolder = client.updateBookmarkFolder(
    folderId = bookmark.getOrThrow().folder!!.id,
    request = UpdateBookmarkFolderRequest(name = "Sweet Breakfast Recipes", custom = mapOf("icon" to "🥞"))
)

// Delete the folder (and all bookmarks in it)
client.deleteBookmarkFolder(folderId = updatedFolder.getOrThrow().id)
Add Chat to my app: getstream.io/SKILL.md

The fastest way to build with Stream. Start a new project or improve an existing one. Full CLI and documentation integration out of the box.


Ask your agent:

/stream Build me a Social App with Feeds and Moderation.
/stream Any livestream calls running?
/stream Feeds Android v3: <Your Question>