Skip to main content
The User Favorites API provides mutations for adding and removing boards from a user’s favorites list.

​
favorite

Adds a board to the authenticated user’s favorites list.
​
id
Id<'boards'>
required
The ID of the board to favorite
​
orgId
string
required
The organization ID that the board belongs to

​
Returns

Returns void on successful addition to favorites.

​
Example

await convex.mutation(api.board.favorite, {
  id: boardId,
  orgId: "org_2abc123def456"
});

​
Behavior

  • Verifies that the board exists before adding to favorites
  • Creates a userFavorites entry linking the user, board, and organization
  • Uses the by_user_board_org index to check for existing favorites

​
Errors

  • Unauthorized: Thrown when the user is not authenticated
  • Board not found: Thrown when the specified board ID doesn’t exist
  • Board already in favorite list: Thrown when the board is already favorited by the user

​
unFavorite

Removes a board from the authenticated user’s favorites list.
​
id
Id<'boards'>
required
The ID of the board to unfavorite

​
Returns

Returns void on successful removal from favorites.

​
Example

await convex.mutation(api.board.unFavorite, {
  id: boardId
});

​
Behavior

  • Verifies that the board exists before attempting to unfavorite
  • Removes the userFavorites entry for the user and board
  • Uses the by_user_board_org index to locate the favorite entry

​
Errors

  • Unauthorized: Thrown when the user is not authenticated
  • Board not found: Thrown when the specified board ID doesn’t exist
  • Board not in favorite list: Thrown when the board is not currently favorited by the user

​
Querying Favorites

To retrieve a user’s favorited boards, use the boards.get query with the favorites parameter.

​
Example

const favoriteBoards = await convex.query(api.boards.get, {
  orgId: "org_2abc123def456",
  favorites: "true"
});

​
Returns

​
boards
Board[]
Array of board objects with isFavorite: true

​
Response Schema

​
Behavior

  • Results are ordered by most recently favorited (descending order)
  • Uses the by_user_org index for efficient querying
  • Only returns boards that exist and are favorited by the authenticated user

​
Schema

The userFavorites table stores the relationship between users and their favorite boards.

​
UserFavorite Object

​
Indexes

The userFavorites table uses the following indexes for efficient queries:
  • by_board: Index on boardId
  • by_user_org: Composite index on userId and orgId
  • by_user_board: Composite index on userId and boardId
  • by_user_board_org: Composite index on userId, boardId, and orgId

Build docs developers (and LLMs) love

Get started for freeTalk to us