Field Mutations

The Field API provides mutations to manage custom fields for your posts.

Create Field

Create a new custom field.

Mutation Structure

mutation CreateField(
  $boardId: String!
  $id: String
  $allowUrlPrefill: Boolean
  $label: String!
  $description: String
  $isRequired: Boolean
  $locations: [String!]
  $options: [FieldOptionInput]
  $type: FieldType!
  $visibility: FieldVisibility
) {
  createField(
    boardId: $boardId
    id: $id
    allowUrlPrefill: $allowUrlPrefill
    label: $label
    description: $description
    isRequired: $isRequired
    locations: $locations
    options: $options
    type: $type
    visibility: $visibility
  ) {
    node {
      id
      label
      type
      isRequired
      visibility
      options {
        id
        name
        color
      }
    }
  }
}

Input Fields

Field	Type	Description
boardId	String!	ID of the board to create the field in
id	String	Optional custom ID for the field
allowUrlPrefill	Boolean	Whether the field can be pre-filled via URL parameters
label	String!	Display label for the field
description	String	Optional description of the field
isRequired	Boolean	Whether the field is required
locations	[String!]	Where the field should be displayed
options	[FieldOptionInput]	Options for SELECTION and SELECTION_MULTI fields
type	FieldType!	Type of the field
visibility	FieldVisibility	Visibility setting for the field

Update Field

Update an existing field.

Mutation Structure

mutation UpdateField(
  $id: String!
  $allowUrlPrefill: Boolean
  $label: String
  $description: String
  $isRequired: Boolean
  $locations: [String!]
  $options: [FieldOptionInput]
  $postId: String
  $type: FieldType
  $visibility: FieldVisibility
) {
  updateField(
    id: $id
    allowUrlPrefill: $allowUrlPrefill
    label: $label
    description: $description
    isRequired: $isRequired
    locations: $locations
    options: $options
    postId: $postId
    type: $type
    visibility: $visibility
  ) {
    node {
      id
      label
      type
      isRequired
      visibility
      options {
        id
        name
        color
      }
    }
  }
}

Input Fields

Field	Type	Description
id	String!	ID of the field to update
allowUrlPrefill	Boolean	Whether the field can be pre-filled via URL parameters
label	String	New display label for the field
description	String	New description of the field
isRequired	Boolean	Whether the field is required
locations	[String!]	New locations where the field should be displayed
options	[FieldOptionInput]	New options for SELECTION and SELECTION_MULTI fields
postId	String	Optional post ID for field updates in post context
type	FieldType	New type for the field
visibility	FieldVisibility	New visibility setting for the field

Delete Field

Delete an existing field.

Mutation Structure

mutation DeleteField($id: String!) {
  deleteField(id: $id) {
    node {
      id
    }
  }
}

Input Fields

Field	Type	Description
id	String!	ID of the field to delete

Update Field Location

Update a field's location settings.

Mutation Structure

mutation UpdateFieldLocation(
  $id: String!
  $location: FieldLocation!
  $isEnabled: Boolean!
) {
  updateFieldLocation(
    id: $id
    location: $location
    isEnabled: $isEnabled
  ) {
    node {
      id
      locations
    }
  }
}

Input Fields

Field	Type	Description
id	String!	ID of the field
location	FieldLocation!	Location to update (NEW_POST, POST, or POST_LIST)
isEnabled	Boolean!	Whether the field should be enabled in this location

Error Handling

Authentication Errors

• Invalid API Key: Returned when the API key is missing or invalid
• Insufficient Permissions: Returned when the user lacks write access to the board
• Write Access Required: Returned when using a read-only API key

Resource Errors

• Field Not Found: Returned when updating/deleting a non-existent field
• Board Not Found: Returned when the board ID is invalid

Example Error Response

{
  "errors": [
    {
      "message": "Field not found",
      "extensions": {
        "code": "NOT_FOUND",
        "field": "id"
      }
    }
  ]
}