# 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

```dart label="Dart"
// Adding a bookmark to a new folder
final bookmark = await feed.addBookmark(activityId: 'activity_123');
// Adding to an existing folder
final bookmarkWithFolder = await feed.addBookmark(
  activityId: 'activity_123',
  request: const AddBookmarkRequest(folderId: 'folder_456'),
);
// Update a bookmark (without a folder initially) - add custom data and move it to a new folder
final updatedBookmark = await feed.updateBookmark(
  activityId: 'activity_123',
  request: const UpdateBookmarkRequest(
    custom: {'color': 'blue'},
    newFolder: AddFolderRequest(
      custom: {'icon': '📁'},
      name: 'New folder name',
    ),
  ),
);
// Update a bookmark - move it from one existing folder to another existing folder
final movedBookmark = await feed.updateBookmark(
  activityId: 'activity_123',
  request: const UpdateBookmarkRequest(
    folderId: 'folder_456',
    newFolderId: 'folder_789',
  ),
);
```

### Removing Bookmarks

```dart label="Dart"
// Removing a bookmark
await feed.deleteBookmark(activityId: 'activity_123', folderId: 'folder_456');
// When you read a feed we include the bookmark
final feedData = await feed.getOrCreate();
print(feed.state.activities[0].ownBookmarks);
```

### Querying Bookmarks

```dart label="Dart"
// Query bookmarks
const query = BookmarksQuery(limit: 5);
final bookmarkList = client.bookmarkList(query);
final page1 = await bookmarkList.get();
// Get next page
final page2 = await bookmarkList.queryMoreBookmarks(limit: 3);
// Query by activity ID
final activityBookmarkList = client.bookmarkList(
  const BookmarksQuery(
    filter: Filter.equal(BookmarksFilterField.activityId, 'activity_123'),
  ),
);
final activityBookmarks = await activityBookmarkList.get();
// Query by folder ID
final folderBookmarkList = client.bookmarkList(
  const BookmarksQuery(
    filter: Filter.equal(BookmarksFilterField.folderId, 'folder_456'),
  ),
);
final folderBookmarks = await 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

```dart label="Dart"
// Query bookmark folders
const query = BookmarkFoldersQuery(limit: 5);
final bookmarkFolderList = client.bookmarkFolderList(query);
final page1 = await bookmarkFolderList.get();
// Get next page
final page2 = await bookmarkFolderList.queryMoreBookmarkFolders(limit: 3);
// Query by folder name (partial matching)
final projectFolderList = client.bookmarkFolderList(
  const BookmarkFoldersQuery(
    filter: Filter.contains(BookmarkFoldersFilterField.name, 'project'),
  ),
);
final projectFolders = await 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.

```dart label="Dart"
// Add a bookmark with a new folder
final bookmark = await feed.addBookmark(
  activityId: activity.id,
  request: AddBookmarkRequest(
    newFolder: AddFolderRequest(
      name: 'Breakfast recipes',
      custom: {'icon': '🍳'},
    ),
  ),
);

// Update the folder
final updatedFolder = await client.updateBookmarkFolder(
  folderId: bookmark.folder!.id,
  request: UpdateBookmarkFolderRequest(
    name: 'Sweet Breakfast Recipes',
    custom: {'icon': '🥞'},
  ),
);

// Delete the folder (and all bookmarks in it)
await client.deleteBookmarkFolder(folderId: updatedFolder.id);
```


---

This page was last updated at 2026-08-07T20:37:29.630Z.

For the most recent version of this documentation, visit [https://getstream.io/activity-feeds/docs/flutter/bookmarks/](https://getstream.io/activity-feeds/docs/flutter/bookmarks/).