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.
const result = await mediator.executeMutation({
type: 'account.update',
accountId: 'account-123'
});
Update account metadata.
type
'account.metadata.update'
required
Mutation type identifier
const result = await mediator.executeMutation({
type: 'account.metadata.update',
accountId: 'account-123'
});
Delete account metadata.
type
'account.metadata.delete'
required
Mutation type identifier
const result = await mediator.executeMutation({
type: 'account.metadata.delete',
accountId: 'account-123'
});
account.logout
Log out from an account.
const result = await mediator.executeMutation({
type: 'account.logout'
});
Authentication
email.login
Log in with email and password.
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.
const result = await mediator.executeMutation({
type: 'email.register'
});
email.verify
Verify email address.
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.
const result = await mediator.executeMutation({
type: 'google.login'
});
Workspaces
workspace.create
Create a new workspace.
type
'workspace.create'
required
Mutation type identifier
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
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
const result = await mediator.executeMutation({
type: 'workspace.delete',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
Update workspace metadata.
type
'workspace.metadata.update'
required
Mutation type identifier
const result = await mediator.executeMutation({
type: 'workspace.metadata.update',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
Delete workspace metadata.
type
'workspace.metadata.delete'
required
Mutation type identifier
const result = await mediator.executeMutation({
type: 'workspace.metadata.delete',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
Spaces
space.create
Create a new space.
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.
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
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
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
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
const result = await mediator.executeMutation({
type: 'space.child.reorder',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
Pages
page.create
Create a new page.
Parent node ID (space, folder, or page)
Page avatar emoji or icon
ID of the node to insert after (for ordering)
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.
const result = await mediator.executeMutation({
type: 'page.update',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
page.delete
Delete a page.
const result = await mediator.executeMutation({
type: 'page.delete',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
Folders
folder.create
Create a new folder.
ID of the node to insert after
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.
const result = await mediator.executeMutation({
type: 'folder.update',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
folder.delete
Delete a folder.
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
ID of the node to insert after
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
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
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
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.
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
const result = await mediator.executeMutation({
type: 'field.name.update',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
field.delete
Delete a database field.
const result = await mediator.executeMutation({
type: 'field.delete',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
Database Views
view.create
Create a database view.
const result = await mediator.executeMutation({
type: 'view.create',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
view.update
Update view configuration.
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
const result = await mediator.executeMutation({
type: 'view.name.update',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
view.delete
Delete a database view.
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
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
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
const result = await mediator.executeMutation({
type: 'select.option.delete',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
Records
record.create
Create a new database record.
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
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
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
New field value (type depends on field type)
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
const result = await mediator.executeMutation({
type: 'record.field.value.delete',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
record.delete
Delete a record.
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
Document ID (same as page/node ID)
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.
Temporary file ID from upload
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.
const result = await mediator.executeMutation({
type: 'file.update',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
file.delete
Delete a file.
const result = await mediator.executeMutation({
type: 'file.delete',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
file.download
Download a file.
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
const result = await mediator.executeMutation({
type: 'temp.file.create',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
Channels
channel.create
Create a new channel.
const result = await mediator.executeMutation({
type: 'channel.create',
accountId: 'account-123',
workspaceId: 'workspace-456',
name: 'general',
avatar: '#'
});
channel.update
Update channel properties.
const result = await mediator.executeMutation({
type: 'channel.update',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
channel.delete
Delete a channel.
const result = await mediator.executeMutation({
type: 'channel.delete',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
Chats
chat.create
Create a direct chat.
const result = await mediator.executeMutation({
type: 'chat.create',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
Messages
message.create
Create a new message.
const result = await mediator.executeMutation({
type: 'message.create',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
message.delete
Delete a message.
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
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
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
Emoji reaction (e.g., ’👍’, ‘❤️’)
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
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
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
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
const result = await mediator.executeMutation({
type: 'node.collaborator.delete',
accountId: 'account-123',
workspaceId: 'workspace-456'
});
Users
users.create
Create new users.
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.
const result = await mediator.executeMutation({
type: 'server.create'
});
server.delete
Disconnect from a server.
const result = await mediator.executeMutation({
type: 'server.delete'
});
Avatars
avatar.upload
Upload a new avatar image.
const result = await mediator.executeMutation({
type: 'avatar.upload',
accountId: 'account-123'
});
Update application metadata.
type
'app.metadata.update'
required
Mutation type identifier
const result = await mediator.executeMutation({
type: 'app.metadata.update'
});
Delete application metadata.
type
'app.metadata.delete'
required
Mutation type identifier
const result = await mediator.executeMutation({
type: 'app.metadata.delete'
});