Status Mutations

The Status API provides mutations to manage post statuses in your board.

Create Status

Create a new custom status.

Mutation Structure

mutation CreateStatus(
  $boardId: String!
  $postId: String
  $id: String
  $color: String!
  $name: String!
) {
  createStatus(
    boardId: $boardId
    postId: $postId
    id: $id
    color: $color
    name: $name
  ) {
    node {
      id
      color
      name
      type
      postVisibility
    }
  }
}

Input Fields

Field	Type	Description
boardId	String!	ID of the board to create the status in
postId	String	Optional post ID to associate with the status
id	String	Optional custom ID for the status
color	String!	Color for the status (for custom display)
name	String!	Name of the status

Return Type

Field	Type	Description
node	Status!	The created status object

Update Status

Update an existing status.

Mutation Structure

mutation UpdateStatus(
  $id: String!
  $color: String
  $name: String
  $postId: String!
  $postVisibility: PostVisibility
) {
  updateStatus(
    id: $id
    color: $color
    name: $name
    postId: $postId
    postVisibility: $postVisibility
  ) {
    node {
      id
      color
      name
      type
      postVisibility
    }
  }
}

Input Fields

Field	Type	Description
id	String!	ID of the status to update
color	String	New color for the status
name	String	New name for the status
postId	String!	ID of the post associated with this status update
postVisibility	PostVisibility	Visibility setting for posts with this status

Return Type

Field	Type	Description
node	Status!	The updated status object

Delete Status

Delete an existing status.

Mutation Structure

mutation DeleteStatus(
  $id: String!
  $postId: String
) {
  deleteStatus(
    id: $id
    postId: $postId
  ) {
    node {
      id
      name
      type
    }
  }
}

Input Fields

Field	Type	Description
id	String!	ID of the status to delete
postId	String	Optional post ID associated with this status deletion

Return Type

Field	Type	Description
node	Status!	The deleted status object

Rearrange Statuses

Reorder the list of statuses.

Mutation Structure

mutation RearrangeStatuses($ids: [String!]!) {
  rearrangeStatuses(ids: $ids)
}

Input Fields

Field	Type	Description
ids	[String!]!	Ordered array of status IDs representing the new order

Return Type

Returns an array of status IDs in their new order.

Status Object

The Status object returned by mutations has the following fields:

Field	Type	Description
id	String!	Status ID
color	String!	Status color (for custom display)
name	String!	Status name
type	StatusType!	Type of status
postVisibility	PostVisibility!	Visibility setting for posts with this status

StatusType Enum

Value	Description
CUSTOM	User-defined status
ARCHIVED	Post is archived
COMPLETED	Post is completed
MERGED	Post is merged with another post
UNASSIGNED	Post has no status assigned

PostVisibility Enum

Value	Description
PUBLIC	Status and posts are visible to all users
PRIVATE	Status and posts are only visible to board members

Error Handling

The Status mutations will return appropriate error messages if:

• Required fields are missing or invalid
• The status ID does not exist
• The user does not have permission to perform the operation
• The board ID is invalid
• The post ID is invalid

Common error scenarios:

{
  "errors": [
    {
      "message": "Status not found",
      "extensions": {
        "code": "NOT_FOUND"
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "Invalid board ID",
      "extensions": {
        "code": "BAD_REQUEST"
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "Insufficient permissions",
      "extensions": {
        "code": "FORBIDDEN"
      }
    }
  ]
}