Mutation

Object

updateActionProject

Update the project for an action

Access: Requires user access to the action and target project

Parameters:

• actionId: The ID of the action to update
• projectId: The ID of the new project (null to unset)
• rank: Optional rank for the action in the new project

Returns: The updated action

bulkUpdateActionStatus

Update status for multiple actions at once.

ALWAYS look for existing statuses in the project. Only add statuses if they're definitely different from the existing ones. Otherwise, don't add them and use the existing ones that have the same meaning.

Examples: Project has statuses: "To Do", "In Progress", "Review feedback", "Done"

Access: Requires user access to all actions

Parameters:

• actionIds: Array of action IDs to update
• workspaceId: The ID of the workspace
• status: The new status to set
• rankInput: Optional rank information for repositioning
• shouldUpdateChildren: Optional flag to update child actions

Returns: Boolean indicating success

updateActionAssignees

Update assignees for an action

Access: Requires user access to the action

Parameters:

• actionId: The ID of the action to update
• assignees: Optional array of user IDs to assign ['none'] to unassign
• placeholderAssignees: Optional array of placeholder IDs to assign
• teamAssignee: Optional team ID to assign
• rankInput: Optional rank information for repositioning
• shouldUpdateChildren: Optional flag to update child actions (default: false)
• externalAssigneeName: Optional name for external assignee
• isAutomated: Optional flag to indicate automated update

Returns: The updated action

updateActionLabels

Update labels for an action

Access: Requires user access to the action

Parameters:

• actionId: The ID of the action to update
• labels: Optional array of label IDs to set, ['none'] to remove all
• rankInput: Optional rank information for repositioning
• shouldUpdateChildren: Optional flag to update child actions
• isAutomated: Optional flag to indicate automated update

Returns: The updated action

updateActionsMilestone

updateActionGithubBranchNames

Update the GitHub branch names associated with an action

Access: Requires user access to the action

Parameters:

• actionId: The ID of the action to update
• githubBranchNames: An array of branch names in the format "Repo:branch-name"

Returns: The updated action

insertAction

Used to create new actions and subactions

Access: Requires user access as well as workspace ID and project ID access.

Errors: Throws error if user does not have access to workspace or project.

bulkInsertActions

Batch insert actions and return the inserted action ids Access: Requires user access to the workspace and projects. Won't add actions to projects that user doesn't have access to. If the user uses phrases like "on my list" or otherwise implies the actions are for themselves, assume the user is the assignee by default. Errors: Throws error if user does not have access to workspace.

setTimeTrackingItemToAction

Add or edit time tracking item for action

Access: Requires user access to the underlying action and related project

Errors: Throws error if user does not have access to action or project.

setActionEstimatedTime

Used to create new action and subaction estimates

Access: Requires user access to the underlying action

Errors: Throws error if user does not have access to action.

bulkUpdateActionLabels

Update labels for the provided action IDs.

Access: Requires user access to all actions

Parameters:

• actionIds: Array of action IDs to update
• workspaceId: The ID of the workspace
• labelIds: Array of label IDs to add or remove
• operation: The operation to perform (ADD, REMOVE)
• shouldUpdateChildren: Boolean to update children
• shouldUpdateRecurring: Boolean to update recurring

Returns: Boolean indicating success

bulkUpdateActionsAssignees

Update actions assignees in bulk

IMPORTANT:

• Set operation will override existing assignees and placeholder assignees.
• Add/pull operation will add/pull assignees and placeholder assignees to existing ones.

The set and add/pull parameters are mutually exclusive. If you want to set the assignees, you should not pass any of the add/pull parameters. If you want to add or pull assignees, you should not pass the set parameter.

Access: Requires user access to all actions

Parameters:

• actionIds: Array of action IDs to update
• workspaceId: The ID of the workspace
• assigneesToSet: Array of user IDs to assign
• assigneesToAdd: Array of user IDs to add
• assigneesToPull: Array of user IDs to remove
• teamAssignee: The ID of the team to assign
• placeholderAssigneesToSet: Array of placeholder IDs to assign
• placeholderAssigneesToAdd: Array of placeholder IDs to add
• placeholderAssigneesToPull: Array of placeholder IDs to remove
• privacy: The privacy of the action
• shouldUpdateChildren: Boolean to update children
• shouldUpdateRecurring: Boolean to update recurring
• updatePlaceholderAssignees: Boolean to update placeholder assignees
• currentAssigneeId: The ID of the current assignee

Returns: Boolean indicating success

setStoryPoints

Set the agile story point value for an action

Access: Requires user access to the action

Parameters:

• actionId: The ID of the action to update
• storyPoints: The new story point value

setActionColor

Set the color of an action to be used in the timeline view.

insertActionLink

updateActionLink

bulkUpsertCustomFields

Creates or updates multiple custom fields at once.

It can be used to upsert custom fields for a project or an action.

Parameters:

• workspaceId: Required. The ID of the workspace to upsert custom fields for.
• customFields: Required. An array of custom fields to upsert.

Examples:

1. Create a custom field (text type) for a project:

{ "workspaceId": "TCB9NnnbcC4BEc2rF", "customFields": [ { "allowMultiSelect": false, "_id": "d6JfiYb34mMb5zNqL", "label": "Test Project Field", "dropdownValues": [], "formula": null, "type": "text", "itemType": "project", "onlyAdminEditable": false, "jiraCustomFieldId": "", "groupIds": [] } ] }

1. Create a custom field (number type) for an action:

{ "workspaceId": "TCB9NnnbcC4BEc2rF", "customFields": [ { "allowMultiSelect": false, "_id": "y7RCztztQ4D36GKk5", "label": "asasas", "dropdownValues": [], "formula": "Test Action Field", "type": "number", "itemType": "action", "onlyAdminEditable": false, "jiraCustomFieldId": "", "groupIds": [] } ] }

When creating custom fields the _id field is generated server-side automatically, so you don't need to provide it. When updating custom fields you must provide old _id and new field data (old field data with new values).

insertGroup

Creates a new group.

It's very useful when there are no group that has the needed members.

Access: Requires user access to the workspace.

Parameters:

• workspace: ID of the workspace
• members: Array of user IDs
• teams: Array of team IDs
• name: Name of the group
• oneToOne: @deprecated do not use this parameter, use 'type' instead
• type: 'dm' (direct message) or 'group' (group chat) or 'thread'
• projectId: ID of the project

Examples:

• Creating a direct message: insertGroup( workspace members: ['user-id-1' (you), 'user-id-2' (other user)] type: 'dm' )
• Creating a group chat: insertGroup( workspace members: ['user-id-1' (you), 'user-id-2' (other user), 'user-id-3' (other user)] type: 'group' )

insertMessage

Creates a new message in a container (group, action, note, goal, or post).

Access: Requires user access to the container

Parameters:

• _id: Random ID
• containerId: ID of the container (id of group, action, note, goal, or post)
• containerType: Type of the container (group, action, note, goal, or post). You should always specify this parameter to avoid errors and confusion.
• body: Message text
• mentions: Array of mentioned user IDs (that are mentioned like @username)
• attachments: Array of file attachments
• userMentionsByGroup: Array of mentioned group IDs
• userMentionsByTeam: Array of mentioned team IDs

Examples:

• Creating a message in a chat: insertMessage( _id containerId - Group ID containerType - 'group' body mentions attachments )
• Creating a comment in an action: insertMessage( _id containerId - Action ID containerType - 'action'. mentions = ["id"] attachments mentionPlaceholderTemplate = "<@id>" body = "Hello <@id>, how are you?" ) NOTE: @id is the actual userId or teamId, e.g. @123 or @team456

Returns the created message with all computed fields.

updateProjectOwner

addProjectOwner

Add a user to the project owner list.

removeProjectOwner

Remove a user from the project owner list.

updateProjectDescription

updateMembersPermissions

Add or remove members to/from a project.

Common use cases:

• Add a new member to a project
• Remove a member from a project
• Update the permission of a member
• Update the sharing type of a member
• Update the automated status of a member

Parameters:

• projectId: Required. The ID of the project to update members permissions for
• memberIds: Optional. The IDs of the users to add as members
• teamIds: Optional. The IDs of the teams to add as members
• permission: Required. The permission to set for the members.
• sharingType: Required. The sharing type to set for the members.
• isAutomated: Optional. Whether the update is automated. Default is false.

Examples:

1. Add a new member to a project

• projectId: 123
• memberIds: [456]
• permission: 'FULL_ACCESS'
• sharingType: 'custom'
• isAutomated: false

1. Remove a member from a project

• projectId: 123
• memberIds: [456]
• permission: 'REMOVE'
• sharingType: 'custom'
• isAutomated: false

restoreDeletedProject

Used to restore deleted projects in the trash bin

Access: Requires project access

Errors: Throws error if user doesn't have access to the project

updateProjectsCustomFields

Enables custom fields for specific projects.

This should be used to enable only project itemType custom fields.

Parameters:

• projectIds: Required. The IDs of the projects to add the custom fields to
• workspaceId: Required. The ID of the workspace to add the custom fields to
• fields: Required. The custom fields to add to the projects

disableProjectsCustomFields

Disables custom fields for specific projects.

This should be used to disable only project itemType custom fields.

Parameters:

• customFieldIds: Required. The IDs of the custom fields to disable
• projectIds: Required. The IDs of the projects to disable the custom fields for
• workspaceId: Required. The ID of the workspace to disable the custom fields for

addActionCustomFields

Enables custom fields for actions in specific projects.

This should be used to enable only action itemType custom fields.

Parameters:

• ids: Required. The IDs of the custom fields to enable
• projectIds: Required. The IDs of the projects to enable the custom fields for
• workspaceId: Required. The ID of the workspace to enable the custom fields for

disableActionCustomFields

Disables custom fields for actions in specific projects.

This should be used to disable only action itemType custom fields.

Parameters:

• customFieldIds: Required. The IDs of the custom fields to disable
• projectIds: Required. The IDs of the projects to disable the custom fields for
• workspaceId: Required. The ID of the workspace to disable the custom fields for
• removeFromActions: Optional. Whether to remove the custom fields from the actions

updateProjectArchived

Update project archived status

Access: Requires user access to the project

Parameters:

• projectId: The ID of the project to update
• archived: The new archived state to set
• includeChildren: Whether to include children in the update

Returns: The updated project

addStatusToProjectView

This mutation is used to add a status to a specific project. ALWAYS run the setCustomStatusColor mutation (setting status color) to set the color of the status afterwards.

setCustomStatusColor

This mutation is used to set the color of a custom status. ALWAYS run it after the addStatusToProjectView mutation (adding new status) to set the color of the new status. Pick the color that would logically fit the status name (e.g. "In Progress" -> "blue", "Done" -> "green", etc.).

Also could be used separately to update or remove the color of the status.

submitTimesheets

Used for submit timesheets button timesheets in "timesheet" tab in "Timesheets" app.

Access: It requires user access.

Errors: Returns specific expected errors if: timesheets array is empty, user is not logged in, user doesn't have access to workspace, user trying to submit timesheets beyond 4 weeks period from start of current week, userId is different from current userId and user is not admin for current workspace, if one of timesheets is locked, approved or waiting for approval

deleteTimesheet

Used for deleting timesheets in "timesheet" tab in "Timesheets" app.

Access: It requires user access.

Errors: Returns specific expected errors if: not deleted timesheet item doesn't exist, user is not timesheet submitter

recoverTimesheet

Used for recovering timesheets in "timesheet" tab in "Timesheets" app. Right after removing should appear toast with "recover" button

Access: It requires user access.

Errors: Returns specific expected errors if: deleted timesheet item doesn't exist, user is not timesheet submitter and returns null if user doesn't have access to workspace

bulkUpdateTimesheetStatus

Used for approve/request changes of timesheets in "My approvals" tab "Timesheets" app.

Access: It requires user access.

Errors: Returns specific expected errors if: returns [] if user not logged in or doesn't have access to workspace, related timesheet docs with status different to Unsubmitted not found, user is not timesheet approval

setTimesheetLock

Used for locking/unlocking editing of timesheets in "Manage" tab "Timesheets" app.

Access: Requires workspace admin access

Errors: Returns specific expected errors if: error if user is not workspace admin, returns null if is not logged in or not deleted not history timesheet with status different to Unsubmitted not found

addCreatorComment

Used for creating creator comments in comment modal in "Timesheets" app.

Access: It requires user access.

Errors: Returns specific expected errors if: not deleted and not marked as history item timesheet doesn't exist, user trying to create comment for timesheet that he didn't create, $text variable is empty string after trim spaces

updateTimesheetComment

Used for updating existing comments in comment modal in "Timesheets" app.

Access: It requires user access.

Errors: Returns specific expected errors if: not deleted and not marked as history item timesheet doesn't exist, user trying to update comment that he didn't create, $text variable is empty string after trim spaces

deleteTimesheetComment

Used for removing existing comments in comment modal in "Timesheets" app.

Access: It requires user access.

Errors: Returns specific expected errors if: not deleted and not marked as history item timesheet doesn't exist, user trying to delete comment that he didn't create

updateTimeEntry

createTimeEntries

updateTimeEntryComment

insertTimeCategory

updateTimeCategory

deleteTimeCategory

createForm

This mutation creates a new form with all its configuration and content. The form can be used to create actions, projects, or send emails based on the target field. Form should use different input elements for different types of data.

createResourcePlaceholder

Create a new resource placeholder for the workspace.

Resource placeholders are virtual team members that can be assigned to projects and actions before actual people are hired or designated for those roles.

IMPORTANT: Only workspace administrators can set billRate and costRate values. Regular users can only set the name and roleTagId.

Use cases: • Planning projects before hiring specific team members • Creating role-based assignments in project templates
• Resource planning and capacity management • Budgeting and cost estimation for future roles

Parameters: • name: Required. The display name for the placeholder (e.g., "Senior Developer", "Marketing Manager") • workspaceId: Required. The workspace where this placeholder will be created • roleTagId: Optional. Associates the placeholder with a specific role/skill tag • billRate: Optional. The hourly billing rate (admin only) • costRate: Optional. The hourly cost rate (admin only)

Returns: The created ResourcePlaceholder object

updateResourcePlaceholder

Update an existing resource placeholder's properties.

This allows modification of placeholder details while preserving the placeholder's identity and existing assignments.

IMPORTANT: Only workspace administrators can modify billRate and costRate values. Regular users can only update the name and roleTagId.

Common use cases: • Refining placeholder role names for clarity • Updating role assignments as requirements change • Adjusting billing/cost rates (admin only) • Associating placeholders with different role tags

Parameters: • id: Required. The ID of the resource placeholder to update • name: Optional. New display name for the placeholder • roleTagId: Optional. New role/skill tag association (can be null to remove) • billRate: Optional. New hourly billing rate (admin only) • costRate: Optional. New hourly cost rate (admin only)

Returns: The updated ResourcePlaceholder object

createResourceAssignment

Create a resource assignment.

IMPORTANT: ALWAYS pass 'fixedDisplayType' and 'allocationType' together.

Possible valid combinations ('allocationType' + 'fixedDisplayType'): • 'hoursPerDay' + 'hours' - when you want to allocate hours per day • 'fixedHours' + 'hours' - when you want to allocate total hours • 'fixedHours' + 'days' - when you want to allocate in days (default work day = 8 hours) • 'fixedHours' + 'percentages' - when you want to allocate in percentages (percentage of the default default work day hours, e,g, 50% = 4 hours)

IMPORTANT: ALWAYS pass 'allocationValue' when allocating by percentage. IMPORTANT: ALWAYS pass 'fixedHours' when allocating by hours or days. IMPORTANT: ALWAYS pass 'hoursPerDay' when allocating by hours per day.

Examples: • Duration: 1 day, allocationType = hoursPerDay, fixedDisplayType = hours, allocationValue = 8, hoursPerDay = 8 • Duration: 5 days, allocationType = hoursPerDay, fixedDisplayType = hours, allocationValue = 8, hoursPerDay = 8 • Duration: 1 day, allocationType = fixedHours, fixedDisplayType = hours, allocationValue = 40, fixedHours = 40 • Duration: 5 days, allocationType = fixedHours, fixedDisplayType = hours, allocationValue = 40, fixedHours = 40 • Duration: 1 day, allocationType = fixedHours, fixedDisplayType = percentages, allocationValue = 50 (percents), fixedHours = 8 (default work day hours) * 1 (days) * 0.5 = 4 • Duration: 5 days, allocationType = fixedHours, fixedDisplayType = percentages, allocationValue = 50 (percents), fixedHours = 8 (default work day hours) * 5 (days) * 0.5 = 20 • Duration: 1 day, allocationType = fixedHours, fixedDisplayType = days, allocationValue = 2 (days), fixedHours = 8 (default work day hours) * 2 = 16 • Duration: 5 days, allocationType = fixedHours, fixedDisplayType = days, allocationValue = 2 (days), fixedHours = 8 (default work day hours) * 2 = 16

updateResourceAssignment

Update a resource assignment. ALWAYS use search to find the resource assignment before updating it. If the resource assignment is not found, DONT RUN THE MUTATION. If the resource assignment is found, update resource assignment.

createDashboard

updateDashboard

Updates an existing dashboard's configuration.

Common use cases:

1. Updating dashboard metadata (title, privacy, etc.)
2. Modifying widget layouts
3. Updating global widget filter

regenerateShareToken

Regenerates the share token for a dashboard

createDashboardWidget

Creates a new dashboard widget with specified configuration. Common configurations by widget type:

1. Chart Widgets (Bar/Line/Pie):

• Set chartType, XAxis, YAxis
• Configure grouping and aggregation
• Set up color schemes
• Use these types of widgets when asked to show something broken down by project, assignee, etc.

1. List Widgets (Actions/Projects):

• Define filters (status, assignee, etc.)
• Set up sorting and grouping
• Configure display options
• When user asks to create a widget for all actions assigned to them, create a widget with type 'myActionsList'
• Use these types of widgets when asked to show something in a list format, like actions, projects, etc.

1. Status Widgets:

• Specify project or goal
• Configure metrics to display
• Set up refresh intervals

1. Custom Widgets:

• Set up embedded content
• Configure interactive elements
• Define data sources

When asked to show something over time, use binBy and binByDateRange parameters.

updateDashboardWidget

Updates an existing dashboard widget's configuration. Common update scenarios:

1. Changing visualization type
2. Updating filters or data source
3. Modifying appearance settings
4. Adjusting metrics or calculations

createGoal

Create a new goal with comprehensive validation rules

IMPORTANT VALIDATION RULES:

Display Type Rules:

• progress: Only works with measurementType null, number, or actions
• number: Only works with measurementType null, number, actions, or overdue
• status: Only works with measurementType status

Measurement Type + Unit Combinations:

• measurementType actions/overdue: Must use measurementUnit actions OR projects
• measurementType number: Must use measurementUnit currency, custom, OR percentage
• measurementType status: Must use measurementUnit subGoals

Measurement Unit + Value + Symbol Rules:

• measurementUnit currency: measurementUnitValue must be one of the supported currency codes (e.g., USD/EUR/JPY/GBP/AUD), symbol $/€/¥/£/AU$ This list is not exhaustive. For additional currencies, specify the ISO 4217 currency code as measurementUnitValue and provide the appropriate symbol. Refer to the application's documentation or configuration for the full list of supported currencies and symbols.
• measurementUnit percentage: measurementUnitValue must be 'percentage', symbol '%'
• measurementUnit actions: measurementUnitValue must be 'actions'
• measurementUnit projects: measurementUnitValue must be 'projects'
• measurementUnit subGoals: measurementUnitValue must be the empty string ("")
• measurementUnit custom: measurementUnitValue can be any string

Action/Project ID Rules:

• actionIds: Requires measurementType actions/overdue + measurementUnit actions + measurementUnitValue 'actions'
• projectIds: Requires measurementType actions/overdue + measurementUnit projects + measurementUnitValue 'projects'

Date Rules:

• Cannot be both ongoingDate AND recurringDate
• Cannot combine ongoingDate with startDate/endDate
• Cannot combine recurringDate with startDate/endDate
• If startDate provided, endDate is required
• startDate must be before endDate

deleteGoal

requestGoalUpdate

updateGoal

Update an existing goal - follows the same validation rules as createGoal

See createGoal mutation for complete validation rule documentation. Key validation reminders:

• actionIds require: measurementType actions/overdue + measurementUnit actions + measurementUnitValue 'actions'
• projectIds require: measurementType actions/overdue + measurementUnit projects + measurementUnitValue 'projects'
• Date combinations: Cannot mix ongoingDate + recurringDate, or ongoingDate/recurringDate + startDate/endDate
• measurementUnit + measurementUnitValue + measurementUnitSymbol must match allowed combinations

recurringRequestGoalUpdate