Skip to main content
The saves namespace provides full CRUD operations on saves, plus utilities for duplicate detection, favorites, archive, and bulk actions.

​
saves.list

​
query
string
Search text to filter saves by title, URL, description, or notes.
​
visibility
'public' | 'private'
Filter by visibility.
​
isArchived
boolean
Filter by archived status. Defaults to false.
​
isFavorite
boolean
Filter to only favorites.
​
collectionId
Id<'collections'>
Filter by collection.
​
tagId
Id<'tags'>
Filter by tag.
​
limit
number
Number of results per page. Default: 20.
​
cursor
string
Pagination cursor from previous response.
​
saves
Save[]
Array of save objects with tags and collections.
​
nextCursor
string | null
Pagination cursor for the next page. null if no more results.
const result = useQuery(api.saves.list, {
  query: "react",
  visibility: "public",
  limit: 20,
});

​
saves.get

Returns a single save with its tags and collections.
​
id
Id<'saves'>
required
The save ID.
const save = useQuery(api.saves.get, { id: saveId });

​
saves.create

Creates a new save with auto-extracted metadata.
​
url
string
required
The URL to save. Will be normalized automatically.
​
visibility
'public' | 'private'
Save visibility. Defaults to user’s default setting.
​
note
string
Personal note (markdown).
​
tagIds
Id<'tags'>[]
Tags to apply.
​
collectionIds
Id<'collections'>[]
Collections to add to. Default tags from collections are auto-applied.
​
source
'web' | 'mobile' | 'extension'
Client source for tracking.
const createSave = useMutation(api.saves.create);

await createSave({
  url: "https://example.com/article",
  visibility: "public",
  note: "Great article on React patterns",
  tagIds: [tagId1, tagId2],
  collectionIds: [collectionId],
  source: "web",
});
On create, Backpocket automatically: normalizes the URL, extracts OG metadata, checks for duplicates, applies collection default tags, and triggers a snapshot for reader mode.

​
saves.update

Updates an existing save’s metadata, tags, or collections.
​
id
Id<'saves'>
required
The save ID.
​
note
string
Updated note content.
​
visibility
'public' | 'private'
Updated visibility.
​
tagIds
Id<'tags'>[]
Replacement tag list (replaces all existing tags).
​
collectionIds
Id<'collections'>[]
Replacement collection list.
const updateSave = useMutation(api.saves.update);

await updateSave({
  id: saveId,
  visibility: "private",
  note: "Updated notes here",
});

​
saves.remove

Permanently deletes a save and its related data (tag associations, collection associations, snapshots).
​
id
Id<'saves'>
required
The save ID to delete.
const removeSave = useMutation(api.saves.remove);
await removeSave({ id: saveId });
Deletion is permanent and cannot be undone. Consider using archive instead.

​
saves.checkDuplicate

Checks if a URL already exists in the user’s library.
​
url
string
required
The URL to check. Will be normalized before comparison.
​
isDuplicate
boolean
Whether the URL already exists.
​
existingSave
Save | null
The existing save if a duplicate is found.
const result = useQuery(api.saves.checkDuplicate, {
  url: "https://example.com/article?utm_source=twitter",
});
// result.isDuplicate === true if already saved (ignoring tracking params)

​
saves.toggleFavorite

Toggles the favorite status of a save.
​
id
Id<'saves'>
required
The save ID.

​
saves.toggleArchive

Toggles the archived status of a save.
​
id
Id<'saves'>
required
The save ID.

​
saves.bulkDelete

Deletes multiple saves at once.
​
ids
Id<'saves'>[]
required
Array of save IDs to delete.

​
saves.bulkUpdateVisibility

Updates visibility for multiple saves.
​
ids
Id<'saves'>[]
required
Array of save IDs to update.
​
visibility
'public' | 'private'
required
The new visibility setting.

​
saves.getCount

Returns the total number of saves in the user’s library.
​
count
number
Total save count.