Overview
The Boards API provides complete control over board creation, modification, layout management, and permissions.
Queries
getPublicBoards
Retrieve all public boards.
const boards = await api.board.getPublicBoards.query();
getAllBoards
Get all boards accessible to the current user.
const boards = await api.board.getAllBoards.query();
Whether the board is publicly accessible
Board creator information
Whether this is the user’s home board
Whether this is the user’s mobile home board
search
Search for boards by name.
const results = await api.board.search.query({
query: "dashboard",
limit: 10,
});
Maximum results to return (1-100)
getBoardByName
Retrieve a complete board by name.
const board = await api.board.getBoardByName.query({
name: "MyDashboard",
});
Board name (alphanumeric, hyphens, and underscores only)
getHomeBoard
Get the user’s home board (respects device type).
const homeBoard = await api.board.getHomeBoard.query();
- Returns user’s designated home board
- Falls back to mobile home board on mobile devices
- Falls back to group home board if user hasn’t set one
- Returns server default if no other options available
exists
Check if a board with the given name exists.
const exists = await api.board.exists.query("MyBoard");
// Returns: true or false
board-create
getBoardPermissions
Get permission configuration for a board.
const permissions = await api.board.getBoardPermissions.query({
id: "board-id",
});
full access
Permissions inherited from groups with global permissions
User-specific permissions for this board
Group-specific permissions for this board
Mutations
createBoard
Create a new board.
const result = await api.board.createBoard.mutate({
name: "MyDashboard",
columnCount: 12,
isPublic: false,
});
board-create
Parameters:
Board name (1-255 characters, alphanumeric, hyphens, underscores)
Number of grid columns (1-24)
Whether the board is publicly accessible
ID of the newly created board
duplicateBoard
Duplicate an existing board with a new name.
await api.board.duplicateBoard.mutate({
id: "source-board-id",
name: "MyBoardCopy",
});
board-create + view access to source board
Parameters:
ID of the board to duplicate
- Duplicates all sections, items, and layouts
- Only copies integrations the user has access to
- User becomes the creator of the new board
renameBoard
Rename an existing board.
await api.board.renameBoard.mutate({
id: "board-id",
name: "NewBoardName",
});
full access
changeBoardVisibility
Change whether a board is public or private.
await api.board.changeBoardVisibility.mutate({
id: "board-id",
visibility: "public", // or "private"
});
full access
Cannot make server home boards private
deleteBoard
Permanently delete a board.
await api.board.deleteBoard.mutate({
id: "board-id",
});
full access
This action is irreversible. All sections, items, and layouts will be deleted.
saveBoard
Save changes to a board’s sections and items.
await api.board.saveBoard.mutate({
id: "board-id",
sections: [
{
id: "section-id",
kind: "empty",
yOffset: 0,
layouts: [...],
},
],
items: [
{
id: "item-id",
kind: "weather",
options: { ... },
advancedOptions: { ... },
integrationIds: [],
layouts: [...],
},
],
});
modify access
Parameters:
Array of section configurations
Array of widget/item configurations
saveLayouts
Manage responsive layouts for a board.
await api.board.saveLayouts.mutate({
id: "board-id",
layouts: [
{
id: "layout-id",
name: "Desktop",
columnCount: 12,
breakpoint: 1200,
},
{
id: "layout-id-2",
name: "Mobile",
columnCount: 4,
breakpoint: 0,
},
],
});
modify access
Layout name (max 32 characters)
Minimum viewport width in pixels (0-32767)
savePartialBoardSettings
Update board appearance and behavior settings.
await api.board.savePartialBoardSettings.mutate({
id: "board-id",
pageTitle: "My Dashboard",
primaryColor: "#FF5733",
opacity: 85,
customCss: ".widget { border-radius: 8px; }",
});
modify access
Available Settings:
backgroundImageAttachment
Background attachment behavior
backgroundImageRepeat
'no-repeat' | 'repeat' | 'repeat-x' | 'repeat-y'
Background repeat mode
backgroundImageSize
'cover' | 'contain' | 'auto'
Background size mode
Primary theme color (hex format)
Secondary theme color (hex format)
Custom icon color (hex format)
itemRadius
'xs' | 'sm' | 'md' | 'lg' | 'xl'
Border radius for widgets
Custom CSS (max 16,384 characters)
Disable status indicators
setHomeBoard
Set a board as the user’s home board.
await api.board.setHomeBoard.mutate({
id: "board-id",
});
view access
setMobileHomeBoard
Set a board as the user’s mobile home board.
await api.board.setMobileHomeBoard.mutate({
id: "board-id",
});
view access
saveUserBoardPermissions
Configure user-specific permissions for a board.
await api.board.saveUserBoardPermissions.mutate({
entityId: "board-id",
permissions: [
{
principalId: "user-id-1",
permission: "view",
},
{
principalId: "user-id-2",
permission: "modify",
},
],
});
full access
Permission Levels:
view - Can view the boardmodify - Can view and modify the boardfull - Full control including permissions and deletion
saveGroupBoardPermissions
Configure group-specific permissions for a board.
await api.board.saveGroupBoardPermissions.mutate({
entityId: "board-id",
permissions: [
{
principalId: "group-id",
permission: "view",
},
],
});
full access
Examples
Create a Complete Board
// 1. Create the board
const { boardId } = await api.board.createBoard.mutate({
name: "TeamDashboard",
columnCount: 12,
isPublic: false,
});
// 2. Configure appearance
await api.board.savePartialBoardSettings.mutate({
id: boardId,
pageTitle: "Team Dashboard",
primaryColor: "#2563eb",
secondaryColor: "#7c3aed",
opacity: 90,
});
// 3. Add sections and widgets
await api.board.saveBoard.mutate({
id: boardId,
sections: [
{
id: createId(),
kind: "empty",
yOffset: 0,
layouts: [],
},
],
items: [
{
id: createId(),
kind: "weather",
options: {
location: { latitude: 40.7128, longitude: -74.0060 },
},
advancedOptions: {},
integrationIds: [],
layouts: [
{
layoutId: "base-layout-id",
sectionId: "section-id",
xOffset: 0,
yOffset: 0,
width: 3,
height: 2,
},
],
},
],
});
Copy Board with Modifications
// Duplicate board
await api.board.duplicateBoard.mutate({
id: "original-board-id",
name: "DevEnvironmentBoard",
});
// Get the new board
const boards = await api.board.getAllBoards.query();
const newBoard = boards.find(b => b.name === "DevEnvironmentBoard");
// Customize it
await api.board.savePartialBoardSettings.mutate({
id: newBoard.id,
primaryColor: "#10b981",
});
