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
`createTag`	Create a new tag	Yes
`updateTag`	Update an existing tag	Yes
`deleteTag`	Delete a tag	Yes
`addTagToGeneration`	Add a tag to a generation	Yes (owner/editor)
`removeTagFromGeneration`	Remove a tag from a generation	Yes (owner/editor)

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 storage artifacts.

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

Arguments

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

Returns

true if deletion was successful.

Authorization

Generation deletion requires authentication and follows these rules:

Board owner can delete any generation on their board
Board editors can only delete their own generations (ones they created)
Board viewers cannot delete any generations
Non-members cannot delete generations

Authorization Examples

# Owner deletes any generation on their board
mutation {
  deleteGeneration(id: "gen-uuid")  # ✅ Allowed
}

# Editor deletes their own generation
mutation {
  deleteGeneration(id: "gen-created-by-editor")  # ✅ Allowed
}

# Editor tries to delete owner's generation
mutation {
  deleteGeneration(id: "gen-created-by-owner")  # ❌ Permission denied
}

# Viewer tries to delete a generation
mutation {
  deleteGeneration(id: "gen-uuid")  # ❌ Permission denied
}

Example

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

warning

This operation is destructive and cannot be undone. The generation record and associated storage artifacts will be permanently deleted.

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
  }
}

Tag Mutations

createTag

Create a new tag for the current tenant. If no slug is provided, one is auto-generated from the tag name.

mutation {
  createTag(input: CreateTagInput!): Tag!
}

Input Type

input CreateTagInput {
  name: String!
  slug: String
  description: String
  metadata: JSON
}

Field	Type	Default	Description
`name`	`String!`	-	Tag display name (required)
`slug`	`String`	Auto-generated	URL-friendly identifier (must be unique per tenant)
`description`	`String`	`null`	Optional description
`metadata`	`JSON`	`null`	Additional metadata

Example

mutation CreateTag {
  createTag(input: {
    name: "Favorite"
    description: "My favorite generations"
  }) {
    id
    name
    slug
    description
    createdAt
  }
}

updateTag

Update an existing tag. Only provided fields are updated.

mutation {
  updateTag(input: UpdateTagInput!): Tag!
}

Input Type

input UpdateTagInput {
  id: UUID!
  name: String
  slug: String
  description: String
  metadata: JSON
}

Field	Type	Description
`id`	`UUID!`	Tag ID (required)
`name`	`String`	New display name
`slug`	`String`	New slug (must be unique per tenant)
`description`	`String`	New description
`metadata`	`JSON`	New metadata

Example

mutation UpdateTag($tagId: UUID!) {
  updateTag(input: {
    id: $tagId
    name: "Top Picks"
    description: "My top picks from all generations"
  }) {
    id
    name
    slug
    description
    updatedAt
  }
}

deleteTag

Delete a tag. This also removes all associations between the tag and any generations.

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

Arguments

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

Returns

true if deletion was successful.

Example

mutation DeleteTag($tagId: UUID!) {
  deleteTag(id: $tagId)
}

warning

This operation is destructive and cannot be undone. The tag will be removed from all generations it was associated with.

addTagToGeneration

Add a tag to a generation. Requires owner or editor role on the generation's board.

mutation {
  addTagToGeneration(generationId: UUID!, tagId: UUID!): Tag!
}

Arguments

Argument	Type	Description
`generationId`	`UUID!`	The generation to tag
`tagId`	`UUID!`	The tag to add

Returns

The Tag that was added.

Example

mutation TagGeneration($genId: UUID!, $tagId: UUID!) {
  addTagToGeneration(generationId: $genId, tagId: $tagId) {
    id
    name
    slug
  }
}

removeTagFromGeneration

Remove a tag from a generation. Requires owner or editor role on the generation's board.

mutation {
  removeTagFromGeneration(generationId: UUID!, tagId: UUID!): Boolean!
}

Arguments

Argument	Type	Description
`generationId`	`UUID!`	The generation to untag
`tagId`	`UUID!`	The tag to remove

Returns

true if the tag was successfully removed.

Example

mutation UntagGeneration($genId: UUID!, $tagId: UUID!) {
  removeTagFromGeneration(generationId: $genId, tagId: $tagId)
}

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​

Authorization​

Example​

regenerate​

Arguments​

Returns​

Example​

uploadArtifact​

Input Type​

Example​

Tag Mutations​

createTag​

Input Type​

Example​

updateTag​

Input Type​

Example​

deleteTag​

Arguments​

Returns​

Example​

addTagToGeneration​

Arguments​

Returns​

Example​

removeTagFromGeneration​

Arguments​

Returns​

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

Authorization

Example

regenerate

Arguments

Returns

Example

uploadArtifact

Input Type

Example

Tag Mutations

createTag

Input Type

Example

updateTag

Input Type

Example

deleteTag

Arguments

Returns

Example

addTagToGeneration

Arguments

Returns

Example

removeTagFromGeneration

Arguments

Returns

Example

Error Handling

Common Errors

Source Files