Skip to main content

Overview

Mutations modify data in the local database and sync changes to the server. All mutations return a MutationResult with success/error status.

Mutation Pattern

All mutations follow this structure:
const result = await mediator.executeMutation({
  type: 'mutation.name',
  accountId: string,
  workspaceId: string,
  // ... mutation-specific parameters
});

if (result.success) {
  console.log('Success:', result.output);
} else {
  console.error('Error:', result.error.code, result.error.message);
}

Accounts

account.update

Update account information.
type
'account.update'
required
Mutation type identifier
accountId
string
required
Account ID
const result = await mediator.executeMutation({
  type: 'account.update',
  accountId: 'account-123'
});

account.metadata.update

Update account metadata.
type
'account.metadata.update'
required
Mutation type identifier
accountId
string
required
Account ID
const result = await mediator.executeMutation({
  type: 'account.metadata.update',
  accountId: 'account-123'
});

account.metadata.delete

Delete account metadata.
type
'account.metadata.delete'
required
Mutation type identifier
accountId
string
required
Account ID
const result = await mediator.executeMutation({
  type: 'account.metadata.delete',
  accountId: 'account-123'
});

account.logout

Log out from an account.
type
'account.logout'
required
Mutation type identifier
const result = await mediator.executeMutation({
  type: 'account.logout'
});

Authentication

email.login

Log in with email and password.
type
'email.login'
required
Mutation type identifier
server
string
required
Server URL
email
string
required
User email
password
string
required
User password
output
LoginOutput
Contains authentication token and user information
const result = await mediator.executeMutation({
  type: 'email.login',
  server: 'https://brainbox.example.com',
  email: '[email protected]',
  password: 'secure-password'
});

if (result.success) {
  const { token, userId, accountId } = result.output;
  console.log('Logged in as:', userId);
}

email.register

Register a new account.
type
'email.register'
required
Mutation type identifier
const result = await mediator.executeMutation({
  type: 'email.register'
});

email.verify

Verify email address.
type
'email.verify'
required
Mutation type identifier
const result = await mediator.executeMutation({
  type: 'email.verify'
});

email.password.reset.init

Initiate password reset.
type
'email.password.reset.init'
required
Mutation type identifier
const result = await mediator.executeMutation({
  type: 'email.password.reset.init'
});

email.password.reset.complete

Complete password reset.
type
'email.password.reset.complete'
required
Mutation type identifier
const result = await mediator.executeMutation({
  type: 'email.password.reset.complete'
});

google.login

Log in with Google OAuth.
type
'google.login'
required
Mutation type identifier
const result = await mediator.executeMutation({
  type: 'google.login'
});

Workspaces

workspace.create

Create a new workspace.
type
'workspace.create'
required
Mutation type identifier
accountId
string
required
Account ID
const result = await mediator.executeMutation({
  type: 'workspace.create',
  accountId: 'account-123'
});

if (result.success) {
  console.log('Created workspace:', result.output.id);
}

workspace.update

Update workspace settings.
type
'workspace.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'workspace.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

workspace.delete

Delete a workspace.
type
'workspace.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'workspace.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

workspace.metadata.update

Update workspace metadata.
type
'workspace.metadata.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'workspace.metadata.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

workspace.metadata.delete

Delete workspace metadata.
type
'workspace.metadata.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'workspace.metadata.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Spaces

space.create

Create a new space.
type
'space.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
name
string
required
Space name
description
string
required
Space description
output.id
string
Created space ID
output.initialPageId
string
ID of the automatically created initial page
const result = await mediator.executeMutation({
  type: 'space.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456',
  name: 'Product Design',
  description: 'Design documentation and resources'
});

if (result.success) {
  console.log('Space created:', result.output.id);
  console.log('Initial page:', result.output.initialPageId);
}

space.delete

Delete a space.
type
'space.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'space.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

space.name.update

Update space name.
type
'space.name.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'space.name.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

space.description.update

Update space description.
type
'space.description.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'space.description.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

space.avatar.update

Update space avatar.
type
'space.avatar.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'space.avatar.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

space.child.reorder

Reorder children within a space.
type
'space.child.reorder'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'space.child.reorder',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Pages

page.create

Create a new page.
type
'page.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
parentId
string
required
Parent node ID (space, folder, or page)
name
string
required
Page name
avatar
string | null
Page avatar emoji or icon
after
string | null
ID of the node to insert after (for ordering)
output.id
string
Created page ID
const result = await mediator.executeMutation({
  type: 'page.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456',
  parentId: 'space-789',
  name: 'Meeting Notes',
  avatar: '📝',
  after: 'page-previous'
});

if (result.success) {
  console.log('Created page:', result.output.id);
}

page.update

Update page properties.
type
'page.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'page.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

page.delete

Delete a page.
type
'page.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'page.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Folders

folder.create

Create a new folder.
type
'folder.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
parentId
string
required
Parent node ID
name
string
required
Folder name
avatar
string | null
Folder avatar
after
string | null
ID of the node to insert after
output.id
string
Created folder ID
const result = await mediator.executeMutation({
  type: 'folder.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456',
  parentId: 'space-789',
  name: 'Documentation',
  avatar: '📁'
});

folder.update

Update folder properties.
type
'folder.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'folder.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

folder.delete

Delete a folder.
type
'folder.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'folder.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Databases

database.create

Create a new database.
type
'database.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
parentId
string
required
Parent node ID
name
string
required
Database name
avatar
string | null
Database avatar
after
string | null
ID of the node to insert after
output.id
string
Created database ID
const result = await mediator.executeMutation({
  type: 'database.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456',
  parentId: 'space-789',
  name: 'Tasks',
  avatar: '✅'
});

database.update

Update database properties.
type
'database.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'database.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

database.delete

Delete a database.
type
'database.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'database.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

database.name.field.update

Update the primary name field for a database.
type
'database.name.field.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'database.name.field.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Database Fields

field.create

Create a new database field.
type
'field.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'field.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

field.name.update

Update field name.
type
'field.name.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'field.name.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

field.delete

Delete a database field.
type
'field.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'field.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Database Views

view.create

Create a database view.
type
'view.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'view.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

view.update

Update view configuration.
type
'view.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'view.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

view.name.update

Update view name.
type
'view.name.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'view.name.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

view.delete

Delete a database view.
type
'view.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'view.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Select Options

select.option.create

Create a select field option.
type
'select.option.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'select.option.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

select.option.update

Update a select option.
type
'select.option.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'select.option.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

select.option.delete

Delete a select option.
type
'select.option.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'select.option.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Records

record.create

Create a new database record.
type
'record.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'record.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

record.name.update

Update record name.
type
'record.name.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'record.name.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

record.avatar.update

Update record avatar.
type
'record.avatar.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'record.avatar.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

record.field.value.set

Set a field value for a record.
type
'record.field.value.set'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
recordId
string
required
Record ID
fieldId
string
required
Field ID
value
FieldValue
required
New field value (type depends on field type)
output.success
boolean
Whether the operation succeeded
const result = await mediator.executeMutation({
  type: 'record.field.value.set',
  accountId: 'account-123',
  workspaceId: 'workspace-456',
  recordId: 'record-789',
  fieldId: 'field-status',
  value: { type: 'select', optionId: 'option-done' }
});

record.field.value.delete

Delete a field value.
type
'record.field.value.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'record.field.value.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

record.delete

Delete a record.
type
'record.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'record.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Documents

document.update

Update document content (CRDT).
type
'document.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
documentId
string
required
Document ID (same as page/node ID)
update
Uint8Array
required
Yjs update binary data
output.success
boolean
Whether the update was applied
import * as Y from 'yjs';

const ydoc = new Y.Doc();
const update = Y.encodeStateAsUpdate(ydoc);

const result = await mediator.executeMutation({
  type: 'document.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456',
  documentId: 'page-789',
  update
});

Files

file.create

Create a new file node.
type
'file.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
parentId
string
required
Parent node ID
tempFileId
string
required
Temporary file ID from upload
output.id
string | null
Created file ID, or null if creation failed
const result = await mediator.executeMutation({
  type: 'file.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456',
  parentId: 'folder-789',
  tempFileId: 'temp-upload-123'
});

file.update

Update file properties.
type
'file.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'file.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

file.delete

Delete a file.
type
'file.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'file.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

file.download

Download a file.
type
'file.download'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'file.download',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

temp.file.create

Create a temporary file for upload.
type
'temp.file.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'temp.file.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Channels

channel.create

Create a new channel.
type
'channel.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
name
string
required
Channel name
avatar
string | null
Channel avatar
output.id
string
Created channel ID
const result = await mediator.executeMutation({
  type: 'channel.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456',
  name: 'general',
  avatar: '#'
});

channel.update

Update channel properties.
type
'channel.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'channel.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

channel.delete

Delete a channel.
type
'channel.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'channel.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Chats

chat.create

Create a direct chat.
type
'chat.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'chat.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Messages

message.create

Create a new message.
type
'message.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'message.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

message.delete

Delete a message.
type
'message.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'message.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Node Interactions

node.interaction.opened

Track that a node was opened.
type
'node.interaction.opened'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'node.interaction.opened',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

node.interaction.seen

Track that a node was seen.
type
'node.interaction.seen'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'node.interaction.seen',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Node Reactions

node.reaction.create

Add a reaction to a node.
type
'node.reaction.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
nodeId
string
required
Node ID to react to
reaction
string
required
Emoji reaction (e.g., ’👍’, ‘❤️’)
output.success
boolean
Whether the reaction was added
const result = await mediator.executeMutation({
  type: 'node.reaction.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456',
  nodeId: 'page-789',
  reaction: '👍'
});

node.reaction.delete

Remove a reaction from a node.
type
'node.reaction.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'node.reaction.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Node Collaborators

node.collaborator.create

Add a collaborator to a node.
type
'node.collaborator.create'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'node.collaborator.create',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

node.collaborator.update

Update collaborator role.
type
'node.collaborator.update'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'node.collaborator.update',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

node.collaborator.delete

Remove a collaborator.
type
'node.collaborator.delete'
required
Mutation type identifier
accountId
string
required
Account ID
workspaceId
string
required
Workspace ID
const result = await mediator.executeMutation({
  type: 'node.collaborator.delete',
  accountId: 'account-123',
  workspaceId: 'workspace-456'
});

Users

users.create

Create new users.
type
'users.create'
required
Mutation type identifier
const result = await mediator.executeMutation({
  type: 'users.create'
});

user.role.update

Update user role.
type
'user.role.update'
required
Mutation type identifier
const result = await mediator.executeMutation({
  type: 'user.role.update'
});

user.storage.update

Update user storage settings.
type
'user.storage.update'
required
Mutation type identifier
const result = await mediator.executeMutation({
  type: 'user.storage.update'
});

Servers

server.create

Connect to a new server.
type
'server.create'
required
Mutation type identifier
const result = await mediator.executeMutation({
  type: 'server.create'
});

server.delete

Disconnect from a server.
type
'server.delete'
required
Mutation type identifier
const result = await mediator.executeMutation({
  type: 'server.delete'
});

Avatars

avatar.upload

Upload a new avatar image.
type
'avatar.upload'
required
Mutation type identifier
accountId
string
required
Account ID
const result = await mediator.executeMutation({
  type: 'avatar.upload',
  accountId: 'account-123'
});

App Metadata

app.metadata.update

Update application metadata.
type
'app.metadata.update'
required
Mutation type identifier
const result = await mediator.executeMutation({
  type: 'app.metadata.update'
});

app.metadata.delete

Delete application metadata.
type
'app.metadata.delete'
required
Mutation type identifier
const result = await mediator.executeMutation({
  type: 'app.metadata.delete'
});

Build docs developers (and LLMs) love