GraphQL Mutations

This page documents all available GraphQL mutations in the Boards API. Mutations are operations that create, update, or delete data.

Mutation Overview

Mutation	Description	Auth Required
`createBoard`	Create a new board	Yes
`updateBoard`	Update an existing board	Yes (owner/admin)
`deleteBoard`	Delete a board	Yes (owner)
`addBoardMember`	Add a member to a board	Yes (owner/admin)
`removeBoardMember`	Remove a member from a board	Yes (owner/admin)
`updateBoardMemberRole`	Change a member's role	Yes (owner/admin)
`createGeneration`	Start a new generation	Yes
`cancelGeneration`	Cancel a pending generation	Yes
`deleteGeneration`	Delete a generation	Yes
`regenerate`	Re-run a generation	Yes
`uploadArtifact`	Upload an artifact from URL	Yes

Board Mutations

createBoard

Create a new board owned by the current user.

mutation {
  createBoard(input: CreateBoardInput!): Board!
}

Input Type

input CreateBoardInput {
  title: String!
  description: String
  isPublic: Boolean = false
  settings: JSON
}

Field	Type	Default	Description
`title`	`String!`	-	Board title (required)
`description`	`String`	`null`	Optional description
`isPublic`	`Boolean`	`false`	Whether board is publicly visible
`settings`	`JSON`	`null`	Custom board settings

Example

mutation CreateMyBoard {
  createBoard(input: {
    title: "AI Art Gallery"
    description: "My collection of AI-generated artwork"
    isPublic: true
    settings: {
      theme: "dark",
      gridColumns: 4
    }
  }) {
    id
    title
    description
    isPublic
    settings
    createdAt
  }
}

updateBoard

Update an existing board. Only the owner or admins can update a board.

mutation {
  updateBoard(input: UpdateBoardInput!): Board!
}

Input Type

input UpdateBoardInput {
  id: UUID!
  title: String
  description: String
  isPublic: Boolean
  settings: JSON
}

Field	Type	Description
`id`	`UUID!`	Board ID (required)
`title`	`String`	New title
`description`	`String`	New description
`isPublic`	`Boolean`	New visibility
`settings`	`JSON`	New settings (merges with existing)

Example

mutation UpdateMyBoard($boardId: UUID!) {
  updateBoard(input: {
    id: $boardId
    title: "Updated Gallery Name"
    isPublic: false
  }) {
    id
    title
    isPublic
    updatedAt
  }
}

deleteBoard

Delete a board and all its generations. Only the owner can delete a board.

mutation {
  deleteBoard(id: UUID!): Boolean!
}

Arguments

Argument	Type	Description
`id`	`UUID!`	Board ID to delete

Returns

true if deletion was successful.

Example

mutation DeleteMyBoard($boardId: UUID!) {
  deleteBoard(id: $boardId)
}

warning

This operation is destructive and cannot be undone. All generations in the board will also be deleted.

addBoardMember

Add a user as a member of a board. Requires owner or admin role.

mutation {
  addBoardMember(input: AddBoardMemberInput!): Board!
}

Input Type

input AddBoardMemberInput {
  boardId: UUID!
  userId: UUID!
  role: BoardRole = VIEWER
}

Field	Type	Default	Description
`boardId`	`UUID!`	-	Board to add member to
`userId`	`UUID!`	-	User to add
`role`	`BoardRole`	`VIEWER`	Role to assign

Example

mutation AddMember($boardId: UUID!, $userId: UUID!) {
  addBoardMember(input: {
    boardId: $boardId
    userId: $userId
    role: EDITOR
  }) {
    id
    members {
      user {
        id
        displayName
      }
      role
      joinedAt
    }
  }
}

removeBoardMember

Remove a member from a board. Requires owner or admin role.

mutation {
  removeBoardMember(boardId: UUID!, userId: UUID!): Board!
}

Arguments

Argument	Type	Description
`boardId`	`UUID!`	Board ID
`userId`	`UUID!`	User ID to remove

Example

mutation RemoveMember($boardId: UUID!, $userId: UUID!) {
  removeBoardMember(boardId: $boardId, userId: $userId) {
    id
    members {
      user {
        id
      }
    }
  }
}

updateBoardMemberRole

Change a board member's role. Requires owner or admin role.

mutation {
  updateBoardMemberRole(
    boardId: UUID!
    userId: UUID!
    role: BoardRole!
  ): Board!
}

Arguments

Argument	Type	Description
`boardId`	`UUID!`	Board ID
`userId`	`UUID!`	User ID to update
`role`	`BoardRole!`	New role

Example

mutation PromoteToAdmin($boardId: UUID!, $userId: UUID!) {
  updateBoardMemberRole(
    boardId: $boardId
    userId: $userId
    role: ADMIN
  ) {
    id
    members {
      user {
        id
      }
      role
    }
  }
}

Generation Mutations

createGeneration

Start a new generation job. The generation runs asynchronously; use subscriptions or polling to track progress.

mutation {
  createGeneration(input: CreateGenerationInput!): Generation!
}

Input Type

input CreateGenerationInput {
  boardId: UUID!
  generatorName: String!
  artifactType: ArtifactType!
  inputParams: JSON!
}

Field	Type	Description
`boardId`	`UUID!`	Board to add the generation to
`generatorName`	`String!`	Name of the generator to use
`artifactType`	`ArtifactType!`	Type of artifact to generate
`inputParams`	`JSON!`	Parameters for the generator (schema varies by generator)

Example

mutation GenerateImage($boardId: UUID!) {
  createGeneration(input: {
    boardId: $boardId
    generatorName: "flux-1-dev"
    artifactType: IMAGE
    inputParams: {
      prompt: "A serene mountain landscape at sunset, digital art"
      width: 1024
      height: 768
      num_inference_steps: 28
      guidance_scale: 3.5
    }
  }) {
    id
    status
    progress
    generatorName
    artifactType
    createdAt
  }
}

Lineage Tracking

Input parameters that reference other generations (by ID) are automatically resolved and tracked as lineage. For example, for image-to-image generation:

mutation ImageToImage($boardId: UUID!, $sourceGenId: UUID!) {
  createGeneration(input: {
    boardId: $boardId
    generatorName: "flux-1-dev-img2img"
    artifactType: IMAGE
    inputParams: {
      image: $sourceGenId
      prompt: "Transform to watercolor style"
      strength: 0.75
    }
  }) {
    id
    inputArtifacts {
      role
      generation {
        id
      }
    }
  }
}

cancelGeneration

Cancel a pending or processing generation.

mutation {
  cancelGeneration(id: UUID!): Generation!
}

Arguments

Argument	Type	Description
`id`	`UUID!`	Generation ID to cancel

Returns

The generation with status updated to CANCELLED.

Example

mutation CancelJob($genId: UUID!) {
  cancelGeneration(id: $genId) {
    id
    status
  }
}

note

Only generations with status PENDING or PROCESSING can be cancelled. Completed or failed generations cannot be cancelled.

deleteGeneration

Delete a generation and its associated files.

mutation {
  deleteGeneration(id: UUID!): Boolean!
}

Arguments

Argument	Type	Description
`id`	`UUID!`	Generation ID to delete

Returns

true if deletion was successful.

Example

mutation DeleteGeneration($genId: UUID!) {
  deleteGeneration(id: $genId)
}

regenerate

Create a new generation using the same parameters as an existing one.

mutation {
  regenerate(id: UUID!): Generation!
}

Arguments

Argument	Type	Description
`id`	`UUID!`	Generation ID to regenerate from

Returns

A new Generation with the same parameters but a new ID.

Example

mutation RegenerateImage($genId: UUID!) {
  regenerate(id: $genId) {
    id
    status
    generatorName
    inputParams
  }
}

uploadArtifact

Upload an artifact from an external URL. This creates a generation record for an externally-created asset.

mutation {
  uploadArtifact(input: UploadArtifactInput!): Generation!
}

Input Type

input UploadArtifactInput {
  boardId: UUID!
  artifactType: ArtifactType!
  fileUrl: String
  originalFilename: String
  userDescription: String
  parentGenerationId: UUID
}

Field	Type	Description
`boardId`	`UUID!`	Board to add the artifact to
`artifactType`	`ArtifactType!`	Type of the artifact
`fileUrl`	`String`	URL to fetch the file from
`originalFilename`	`String`	Original filename
`userDescription`	`String`	User-provided description
`parentGenerationId`	`UUID`	Optional parent generation for lineage

Example

mutation UploadImage($boardId: UUID!) {
  uploadArtifact(input: {
    boardId: $boardId
    artifactType: IMAGE
    fileUrl: "https://example.com/my-image.png"
    originalFilename: "my-image.png"
    userDescription: "Reference image for style transfer"
  }) {
    id
    status
    storageUrl
    thumbnailUrl
  }
}

Error Handling

Mutations return errors in the standard GraphQL format:

{
  "data": {
    "createBoard": null
  },
  "errors": [
    {
      "message": "Not authenticated",
      "path": ["createBoard"],
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

Common Errors

Code	Description
`UNAUTHENTICATED`	No valid authentication token
`FORBIDDEN`	User lacks permission for this operation
`NOT_FOUND`	Referenced resource doesn't exist
`BAD_USER_INPUT`	Invalid input parameters

Source Files

Mutation definitions are implemented in:

packages/backend/src/boards/graphql/mutations/root.py
packages/backend/src/boards/graphql/resolvers/

Mutation Overview​

Board Mutations​

createBoard​

Input Type​

Example​

updateBoard​

Input Type​

Example​

deleteBoard​

Arguments​

Returns​

Example​

addBoardMember​

Input Type​

Example​

removeBoardMember​

Arguments​

Example​

updateBoardMemberRole​

Arguments​

Example​

Generation Mutations​

createGeneration​

Input Type​

Example​

Lineage Tracking​

cancelGeneration​

Arguments​

Returns​

Example​

deleteGeneration​

Arguments​

Returns​

Example​

regenerate​

Arguments​

Returns​

Example​

uploadArtifact​

Input Type​

Example​

Error Handling​

Common Errors​

Source Files​

Mutation Overview

Board Mutations

createBoard

Input Type

Example

updateBoard

Input Type

Example

deleteBoard

Arguments

Returns

Example

addBoardMember

Input Type

Example

removeBoardMember

Arguments

Example

updateBoardMemberRole

Arguments

Example

Generation Mutations

createGeneration

Input Type

Example

Lineage Tracking

cancelGeneration

Arguments

Returns

Example

deleteGeneration

Arguments

Returns

Example

regenerate

Arguments

Returns

Example

uploadArtifact

Input Type

Example

Error Handling

Common Errors

Source Files