Skip to main content
The Board Operations API provides mutations and queries for managing boards in your organization.

​
create

Creates a new board in the specified organization.
​
orgId
string
required
The organization ID where the board will be created
​
title
string
required
The title of the board

​
Returns

Returns the board ID of the newly created board.
​
boardId
Id<'boards'>
The unique identifier for the created board

​
Response Schema

​
Example

const boardId = await convex.mutation(api.board.create, {
  orgId: "org_2abc123def456",
  title: "Q4 Product Roadmap"
});

​
Errors

  • Unauthorized: Thrown when the user is not authenticated

​
update

Updates the title of an existing board.
​
id
Id<'boards'>
required
The ID of the board to update
​
title
string
required
The new title for the board (max 60 characters)

​
Returns

Returns null on successful update.

​
Example

await convex.mutation(api.board.update, {
  id: boardId,
  title: "Updated Q4 Roadmap"
});

​
Errors

  • Unauthorized: Thrown when the user is not authenticated
  • Title is required: Thrown when the title is empty or only whitespace
  • Title cannot be more than 60 characters: Thrown when the title exceeds the maximum length

​
remove

Deletes a board and removes it from all user favorites.
​
id
Id<'boards'>
required
The ID of the board to delete

​
Returns

Returns void on successful deletion.

​
Example

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

​
Behavior

  • Automatically removes the board from any user’s favorites before deletion
  • Permanently deletes the board from the database

​
Errors

  • Unauthorized: Thrown when the user is not authenticated

​
get

Retrieves a single board by its ID.
​
id
Id<'boards'>
required
The ID of the board to retrieve

​
Returns

​
board
Board | null
The board object if found, or null if the board doesn’t exist

​
Response Schema

​
Example

const board = await convex.query(api.board.get, {
  id: boardId
});

if (board) {
  console.log(board.title);
}

Build docs developers (and LLMs) love

Get started for freeTalk to us