Mutation Object
Fields
#
insertActionLink
Creates a dependency between two existing actions. Create the actions first, then pass the predecessor action (the one that blocks) as source and the dependent/successor action that waits on it as target. Supports FS (finish-to-start), SS (start-to-start), FF (finish-to-finish), and SF (start-to-finish). An existing source/target link is returned unchanged.
updateActionLink
Updates the lag or dependency type for an existing action dependency.
addStatusToProjectView
Adds a status to a project's workflow. Use setCustomStatusColor afterward when the status also needs a custom color.
claimActionHighwayRun
Claims operational ownership for an accepted Highway run; history stays in Highway.
bulkUpdateActionsType
Sets the card type (action, risk, issue, decision, and so on) on one or more actions in a workspace; rank optionally repositions them. Proposal review cards keep their type, and the proposal type cannot be assigned.
Access: logged-in workspace members; only actions the caller can access are updated. Errors: no access to any target action; proposal type locked or not assignable.
requestActionUpdate
Asks an action's assignees (or its team assignee's members) for a status update by sending them a notification and inbox item.
Access: any logged-in user. Errors: action not found.
bulkUpdateActionsPriorityLevelId
Sets or clears the priority level for specified actions. Use a priorityLevelId returned by getPriorityLevels; null clears the priority. Requires access to every target action; shouldUpdateRecurring also updates recurring instances.
bulkInsertFilesToAction
Attaches existing Hive file IDs to an action. Use insertActions attachments while creating a new action. Loading file content does not attach it.
addActionMailMessage
Attach an existing provider mail thread to an action. The mailMessage threadId must be the provider thread ID, not an individual message ID. Duplicate thread links are idempotent.
copyAction
Copy/duplicate an action including its subactions, attachments, approval rounds, and dependencies. Returns the newly created action.
bulkUpdateActionsTitles
Update different titles for multiple actions at once
Access: Requires user access to all actions
Parameters:
- actionTitleUpdates: Array of {actionId, title} pairs to update
- workspaceId: The ID of the workspace
Behavior:
- Empty titles are not allowed (will throw error)
- Only updates the specific actions in the batch (does not update recurring series)
Returns: Boolean indicating success
bulkUpdateActionDescription
Updates descriptions on specified actions. Prefer markdownDescription for Markdown-authored content; it is converted to stored HTML. If both formats are supplied, description takes precedence. Requires access to every target action.
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
Sets the status of specified actions using an existing project or workspace status name. Reuse an existing status with the same meaning instead of creating a duplicate. Can also reposition actions and apply the status to children; requires access to every target action. Pass expectedStatus to make the move conditional: actions no longer in that status are left alone instead of being overwritten. It cannot be combined with rankInput or shouldUpdateChildren — the rank write is a second, unconditional update and the child cascade is fire-and-forget, so neither can honour the condition.
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
batchUpdateActionsDates
Update multiple actions with distinct start and end dates in one request. Access: Requires user access to all actions. Dates locked with lockDates are skipped unless the caller is a workspace admin or project owner. Set shouldTriggerAutoScheduling to false to write the requested dates without shifting dependency-linked actions. This does not disable project actionDateSync: non-recurring parents with active subactions derive their dates from those children and ignore direct parent date writes, while subaction updates may recompute parent and ancestor date ranges.
shiftUnfinishedDescendantDates
Shift visible, unfinished dated descendants at every depth using REST calendar semantics. Parent-project weekends determine the offset; each descendant's weekends and holidays adjust its dates. The parent deadline is not written directly; normal date synchronization may recalculate ancestors. Inaccessible descendants stay untouched; locked dates follow existing edit policy. Requires date-edit permission on the parent in workspaceId. Dates must be midnight UTC. This is a non-idempotent write; dry runs simulate it. Returns only readable descendants.
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
appendHighwayGateResult
Append a highway gate result to an action's highway log. Used by Highway autonomous pipeline agents after each gate completes.
Access: Requires user access to the action. Errors: Throws if user is not logged in or lacks action access.
upsertHighwayHandoff
Upsert compact Highway handoff context for downstream gates. Stored on customDataStore.highwayHandoff for the current run.
Access: Requires user access to the action.
appendHighwayRunStep
Append a latest-run Highway script step. A new agentRunId replaces the previous run blob.
Access: Requires user access to the action.
sendHighwayFollowupCommand
Send a follow-up command to a Highway Cloud Agent run associated with an action. Validates the agentRunId belongs to the action's highway data before proxying.
Access: Requires user access to the action. Errors: Throws if agentRunId is not found in the action's highway log.
stopHighwayAgent
Stop a Highway Cloud Agent run associated with an action. Validates the agentRunId belongs to the action's highway data before proxying. Access: Requires user access to the action. Errors: Throws if agentRunId is not found in the action's highway log.
startHighwayAgent
Start a Highway Admin run for an action. Fresh mode clears Highway execution metadata; partial targets resume existing scripted state and run only the selected scope. A force gate resumes at that gate and continues through the remaining workflow. Access: Highway admin for ordinary starts; action write access for saved question reconciliation. Question reconciliation uses the owning run's saved revision and ignores replaced or cancelled owners.
appendHighwayQuestion
Append one pending Highway question, or one scripted-planning question batch, to an action. Used by Highway agents when product or technical clarification is required between runs.
Access: Requires user access to the action. Errors: Throws when a pending batch already exists, options are invalid, or agentRunId is unknown.
clearHighwayData
Wipe all Highway data from an action: gate log, latest-run step log, handoff context, questions, and planning state. Does not stop any in-flight Highway agent run.
Access: Requires non-read-only user access to the action.
updateActionGitlabBranchNames
Update the GitLab branch names associated with an action
Access: Requires user access to the action
Parameters:
- actionId: The ID of the action to update
- gitlabBranchNames: An array of branch names in the format "Repo:branch-name"
Returns: The updated action
updateActionLayout
Update action card visibility settings. Pass null to restore the default layout. Access: Requires edit access to the action.
bulkInsertActions
Creates Hive action cards. Use explicit ranks when exact ordering matters. The result maps each inputIndex to its rank, actionId, title, and URL for parent or dependency references. Set layout.hiddenSections to hide supported card sections. Requires workspace access and create permission in every destination project, including inherited parent projects. Public visibility alone grants no write access; read-only users, including admins, cannot create actions there. A denied destination rejects the entire batch before insertion. When the user says "on my list" or otherwise implies personal ownership, use the caller as assignee by default.
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
Sets planned effort on an action in seconds as a total, per-assignee estimates, or both. Use addActionActualTime for actual time on an action and createTimeEntries for timesheet entries. Requires action time-tracking write access and an enabled workspace.
setActionAttachmentAiProofingGuideline
Mark or unmark an action attachment as AI proofing guidelines for the action and all subactions. Folder attachments include supported nested files. Access: action editors in a workspace with Proofing & Approvals enabled. Errors: inaccessible action, missing attachment, unsupported source. Safe to repeat; use enabled: false to remove the designation. Does not modify other attachments.
pullActionAttachment
Removes one attachment from an action or action comment. Use the attachmentId returned by getActions or getActionComments and call once per attachment. Comment attachments can be removed by their sender, a project owner, or a workspace admin; action access is required.
updateActionsSection
Moves existing actions in one project into a project section. Pass null to ungroup them. Access: Requires access to every action and its project, plus permission to update sections. Errors: Rejects an empty batch, inaccessible actions, or sections/actions from another project or workspace before making changes. Other section memberships and unrelated action data are preserved. A supplied rank applies to every action; modification metadata is refreshed.
updateLinkedProjectsList
Replaces the projects in which an action also appears. The action's home project is ignored, and changes propagate to subactions. Pass the complete desired list; project linking must be enabled for the workspace and the caller must have action access.
bulkUpdateActionsFollowers
Adds or removes the current user as a follower on specified actions.
bulkUpdateActionLabels
Sets, adds, or removes labels on specified actions. SET replaces the complete label list;
ADD and REMOVE update it incrementally. Use SET with an empty list or ["none"] to clear all
labels. Requires access to every target action.
SET and ADD fail with "Labels do not exist or were deleted:
bulkUpdateActionsAssignees
Replaces, adds, or removes user and placeholder assignees on specified actions. SET fields replace existing user and placeholder assignees and cannot be combined with incremental add or remove fields. Can also apply team, privacy, child, and recurring options; requires access to every target action.
bulkUpdateActionsProject
Moves specified actions into a project, or removes their project when projectId is null. Prefer this bulk operation for one or many MCP action moves.
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
updateActionSnoozeDate
Snoozes an action, hiding it from the caller's task list until the specified date. A null snoozeDate removes the snooze. Requires access to the action.
bulkUpdateActionCustomFields
Sets or clears one custom field on specified actions. Supply only the value field matching the custom-field type: value for text, numberValue for numbers, dateValue for dates, or selectedValues for select, user, and project fields. Pass null or an empty matching value to clear the field. Requires access to every target action and rejects missing fields or values whose shape does not match the field type.
updateActionParent
Moves an action beneath another action, or promotes it to the top level when parentId is omitted or null. rank or useLowestRank controls placement; skipSyncActionDates prevents date synchronization. Returns the updated action.
bulkUpdateActionsExternalAccessV2
Updates whether external members can access selected actions and all of their descendants. Returns which action ids were updated and which were skipped because they are ineligible.
bulkDeleteActions
Deletes specified Hive action cards and their subactions. Access: requires access to the target actions.
bulkArchiveActions
Archives or restores specified Hive action cards. Requires concrete, non-empty actionIds. Use only for Hive actions, not email, inbox, or message cleanup.
updateActions
Applies the same field patch to specified actions. Omitted fields remain unchanged; explicit null clears supported nullable fields. Replacement collections cannot be combined with their incremental add or remove fields. Prefer one call over multiple field-specific updates. Requires access to every target action and rejects empty targets or patches, blank title or status, invalid colors or progress, and conflicting assignee operations.
createActivityFeed
Creates an activity feed entry and sends its configured notification.
updateAiIntakeAssessmentWorkflow
Configures the Hive-managed AI intake assessment workflow. New top-level actions in the selected projects are assessed when enabled. Access:
- Workspace admins only. Errors:
- "User is not logged in" if no user session.
- "User does not have access to workspace" if the user is not a workspace member.
- "Only workspace admins can manage AI intake assessment" if the user is not an admin.
- "One or more selected projects are unavailable" if project validation fails.
- "Select at least one project before enabling AI intake assessment" if enabled without scope.
transferBuzzAutomationOwner
Hand off a Buzz automation in one transaction: the requested snippets and workflows, the workflows and snippets tied to them through Run-a-snippet steps that have the same owner, and the API-key/session connections those snippets use that the owner holds. Either everything moves or nothing does. Nobody is notified. createdBy never changes; runs execute as the new owner from then on.
An email-received trigger watches the owner's inbox, so such a workflow moves only when its trigger names the new owner's own connected inbox; its watch is then registered for the new owner once the transfer commits.
Access: a Hive superadmin (full member of the workspace) may hand off to any full member of the workspace or to themselves; a workspace system admin only to themselves. Everything in the handoff must belong to the workspace and currently to one Hive superadmin: handoffs move staff-built work to the customer, never customer-owned work.
Errors: every message in the OWNERSHIP_TRANSFER_ERRORS enum, plus "Snippet not found" and "App workflow not found" for an id outside the workspace, and "User does not have access to workspace" for an actor who is not a full member.
insertApprovalRound
Creates an approval round with an initial empty stage. Add approvers separately with changeApprovalStageApprover.
requestApprovals
Request approvals from all approvers in an approval round. Notifies approvers and marks the round as requested. Use this after setting up all stages and approvers to officially request their review.
insertApprovalStage
Adds an empty approval stage to an approval round. Add approvers separately with changeApprovalStageApprover.
changeApprovalStageApprover
Adds or replaces a user, team, placeholder, or external approver at a numbered position in an approval stage. An existing approver at that zero-based index is replaced; an index beyond the current list appends an approver.
updateApprovalAgentReviewSettings
Saves Buzz's review settings for his approval in a stage before requesting the review. Replaces the saved settings: preserve existing categories and other choices when changing references. A nonempty guidelineFileIds list selects those references; omitted or empty uses all applicable references. Access: requires access to the action containing the approval stage and an existing Buzz approval.
applyApprovalTemplate
Applies an approval template to an action, creating its configured rounds, ordered stages, and approvers.
createAiProofingLearnedInstruction
Adds a learned instruction that AI Proofing applies to future reviews in the workspace. HTML is stripped; origin ANNOTATION with sourceAnnotationId records the proof comment it came from, and origin SUGGESTION with sourceSuggestionId records the AI suggestion it came from.
Access: workspace admins for workspace scope; project editors for project scope. Errors: empty text, over 1,000 characters, duplicate instruction, workspace limit of 50.
updateAiProofingLearnedInstruction
Rewrites the text of an existing AI Proofing learned instruction.
Access: workspace admins for workspace scope; project editors for project scope. Errors: not found, empty text, over 1,000 characters, duplicate instruction.
deleteAiProofingLearnedInstruction
Removes an explicit instruction or suppresses an inferred preference so it cannot be automatically relearned.
Access: workspace admins for workspace scope; project editors for project scope. Errors: not found.
createBuzzSnippet
Create a workspace-level Buzz snippet draft. Publish it before normal chat runs. Declare allowedTools/externalConnections for every Hive tool, HTTP connection, or MCP tool used by the code.
editBuzzSnippetDraft
Edit existing snippet code with ordered exact replacements, without resending the complete file. Access: snippet owner, shared editor, or authorized sharing bypass. Errors: stale source, ambiguous match, invalid JavaScript, manifest violation, reused operationId. Read affected code with getBuzzSnippetSource. The entire batch is atomic and syntax-checked; rejection applies no changes. A successful edit creates a new draft, preserves its source version as a checkpoint, and leaves the published version intact. Retry the same input/operationId after an interrupted response to recover its receipt. Use a new operationId for different edits. After a stale-source error re-read latestVersionId and reapply the intended change. After two identical failures stop and report the blocker. Dry-run the returned version and check the requested business output before publishing. Report saved, tested and published separately. The receipt's tested/published false describe what this edit operation itself did; isCurrent false means later work superseded or modified its result.
updateBuzzSnippetDraft
Update or create the latest draft version for an existing Buzz snippet. Before editing, load the current version and preserve existing allowedTools, externalConnections, inputSchema, and outputSchema unless intentionally changing them. Only the owner or someone the snippet is already shared with may change sharingType/sharedWith: a Hive superadmin editing a snippet they reached through the sharing bypass may change everything else, but a sharing change errors with SHARING_CHANGE_NOT_AUTHORIZED ("Only the snippet owner or someone it is shared with can change who this snippet is shared with"). Resending the current sharing values is not a change.
publishBuzzSnippetVersion
Publish a draft/latest Buzz snippet version so Buzz can run it from chat. Publish only after dryRunBuzzSnippetVersion returns success true and its output matches the requested outcome; a returned failure report is not a successful dry run, and neither is empty external data or a wrong response shape, even when the code ran. Publishing disables the previously published version, so it is refused while other snippets still pin that version by versionId in a runBuzzSnippetVersion call — the error lists them.
runBuzzSnippetVersion
Start a published Buzz snippet run asynchronously. Returns immediately with runId and status running. Call wait with event buzz_snippet_run and scope.runId, then summarize when the thread resumes.
dryRunBuzzSnippetVersion
Start an async dry-run of a draft/latest Buzz snippet version. Returns runId immediately; use wait with buzz_snippet_run before publishing. success on the final run record means the output passed semantic review.
testBuzzSnippetHTTPRequest
Test a single HTTP connection request before embedding it in snippet code. For snippets that use buzz.http, call this before createBuzzSnippet/updateBuzzSnippetDraft and copy the working method/path/request shape plus response shape into externalConnections.httpConnections[].samples.
testBuzzSnippetMCPTool
Test a single MCP tool call before embedding it in snippet code.
disableBuzzSnippet
Disable the currently published version of a Buzz snippet.
startCustomAppAuthoring
Starts one server-bound App Studio authoring thread and dispatches Buzz to build the app. Returns once the run is dispatched, not once the app is built: poll getBuzzMessages with the returned thread _id for Buzz's reply and its build tool results, and getCustomAppVersions for the new version and its buildStatus. requestId is the client-generated thread id and makes the call idempotent — repeating it re-enters the same thread instead of starting a second one. initialPrompt may carry code verbatim: it is HTML-escaped, not stripped, and one longer than 1,000,000 characters of escaped text is refused rather than truncated, so a brief is never quietly shortened before Buzz builds from it. Use continueCustomAppAuthoring for every turn after the first. Access: authenticated member of an App Studio workspace with Buzz enabled. Errors: workspace without App Studio, disabled Buzz, invalid workspace access, a requestId that belongs to another thread, a missing initialPrompt for a new thread, an initialPrompt that contradicts the one the thread already started from, or an initialPrompt over the length ceiling.
resolveCustomAppAuthoringThread
Open a private editing conversation without starting a build. Access: app owner or editor, with workspace and Buzz access. Errors: unavailable app, unauthorized workspace, or disabled App Studio/Buzz.
continueCustomAppAuthoring
Appends one server-persisted user turn to an App Studio authoring thread and dispatches Buzz. Returns once the run is dispatched, not once the edit is built: poll getBuzzMessages for the assistant reply and for the edit_custom_app and build_custom_app tool results, which carry the compile diagnostics, and getCustomAppVersions for the new version and its buildStatus. requestId is the client-generated message id and makes the call idempotent — repeating it re-delivers the same turn instead of appending a second one. text may carry code verbatim: it is HTML-escaped, not stripped, and a turn longer than 1,000,000 characters of escaped text is refused rather than truncated, so a turn never reaches Buzz half-read. Access: the thread's creator, in an App Studio workspace with Buzz enabled. Errors: workspace without App Studio, disabled Buzz, foreign or non-authoring thread, empty text, or text over the length ceiling.
updateBuzzThreadTodos
Update todos for a Buzz thread. Use merge=true to update existing todos by ID, merge=false to replace all todos.
updateCustomAppSharing
App Studio workspaces only. Replace who can run one Custom App, and optionally who can edit it. Run sharing and editors are independent; recipients run the current published version. Access: authenticated Custom App owner with workspace access; editors cannot change sharing. Errors: unavailable environment, invalid sharing type, custom sharing without people, a person or editor outside the workspace, Custom App not found, or inaccessible workspace.
updateCustomAppDetails
App Studio workspaces only. Change an editable Custom App's name, description, or both without creating a version. Access: authenticated Custom App owner or editor with workspace access. Errors: unavailable environment, neither name nor description given, invalid name, description too long, Custom App not found, or inaccessible workspace.
deleteCustomField
Permanently deletes a custom field from the workspace.
This mutation removes a custom field definition and optionally removes all existing values of this field from actions and projects. This is a destructive operation that cannot be undone.
Access: Requires workspace admin access
Returns: The deleted CustomField object (marked as deleted)
Errors:
- Throws error if user doesn't have workspace admin access
- Throws error if custom field doesn't exist
- Throws error if custom field is already deleted
bulkUpsertCustomFields
Creates or updates action and project custom-field definitions. New fields receive generated IDs; updates use the existing field ID with the replacement definition.
createDashboardV2
Creates a Hive dashboard with typed filters and optional sharing settings.
updateDashboardV2
Updates a Hive dashboard, including its title, sharing, filters, styling, and layout. Dashboard layout uses a 48-column grid; provide layout only for an explicit widget move or resize request.
transferDashboardOwnership
Transfers ownership of a dashboard to another workspace member. Access: Dashboard creator or workspace admin. Previous owner remains on sharingWith for me/custom privacy. Errors:
- "User is not logged in" if no user session.
- "No access" if caller is not the creator or a workspace admin.
- "Overview dashboards cannot transfer ownership" for overview dashboards.
- "New owner must be different from the current owner" if newOwnerId matches createdBy.
- "New owner is not a member of this workspace" if the target lacks workspace access.
- "Dashboard not found" / access errors if the dashboard is missing or inaccessible.
updateMyHomeScratchPad
Replaces signed-in user's My Home Scratch Pad Slate document. Read it first and retain rich text and notes outside requested edits. Access: workspace member and owner of the private Home Overview dashboard. Errors: missing Home view, Scratch Pad, workspace access, or stale content. On stale content, read again and reapply the requested edit.
createDashboardWidgetV2
Creates a widget on an existing Hive dashboard. Supports charts, lists, status summaries, and custom widgets with type-specific data, filters, layout, and presentation settings. Use the dashboard ID from current context; otherwise call getDashboards and ask which dashboard to use. Never invent containerId; unknown IDs fail with NOT_FOUND.
createDashboardWidgets
Adds several widgets to one existing Hive dashboard in a single call, in reading order. Use it to build a whole dashboard or report: each item takes the same widget input as createDashboardWidgetV2 plus an optional position on the dashboard's 48-column grid. Items without a placement are auto-placed. Returns the created widgets in input order. Nothing is created when any item is invalid.
updateDashboardWidget
Updates an existing dashboard widget's configuration. Common update scenarios:
- Changing visualization type
- Updating filters or data source
- Modifying appearance settings
- Adjusting metrics or calculations
updateDashboardWidgetV2
Updates an existing dashboard widget using a single input object. V2 replacement for updateDashboardWidget — all fields are in UpdateDashboardWidgetInput.
prepareFileLibraryUploads
Prepares File Library metadata and signed direct-upload URLs for one to 20 files. Each path must include a root segment and use forward slashes with 2–10 segments, be at most 2048 characters, and imply at most 40 unique folders. The client must PUT binary bytes outside GraphQL using Content-Type from the result and x-amz-acl: private when required by the signed URL. URLs expire after 15 minutes while pending. Reuse the same uploadKey and manifest to retry without creating duplicates; split larger batches into chunks with the same key. Access: Authenticated users with write access to the workspace and parent folder. Errors: Throws for invalid paths, inaccessible parents, or conflicting retries.
completeFileLibraryUploads
Completes direct uploads after verifying each stored object's size. Call after the client PUTs binary data outside GraphQL; pending records remain until explicit completion. Access: Authenticated users who created the protocol upload files. Errors: Throws when a file is inaccessible or its stored object is missing or mismatched.
insertFile
Creates a workspace file and returns a signed upload URL. PUT the bytes to uploadUrl with the same Content-Type, then call unsetFileLoading. To attach the file to an action, pass its ID to attachFilesToAction. The file is not added to the File Library. Access: Authenticated workspace members. Errors: Throws when workspace access is denied.
unsetFileLoading
Marks a file upload as finished after its bytes are stored. Call after the PUT to the insertFile uploadUrl. Errors: Throws when the file does not exist.
addFilesToFileLibrary
Add existing Hive files to the explicit File Library repository without duplicating or deleting the underlying files. If parentId is omitted and no sharingType is provided, files default to Only me. If parentId is provided and no sharingType is provided, files inherit folder access.
removeFilesFromFileLibrary
Remove existing files from the explicit File Library repository without deleting the files or removing their action/message attachments.
updateFileDescription
Update a File Library file's description. Access: workspace members with edit access to the file. Errors: inaccessible, deleted or immutable files; description over 2,000 characters.
renameFileStoreNode
Renames a File Library file or folder; renaming a folder updates the paths of its subfolders.
Access: workspace members with edit access to the item. Errors: item not found; empty name.
trashFileStoreNodes
Removes File Library items of one type. Folders (with their subfolders) are moved to trash; files, including those inside trashed folders, leave the File Library but are not deleted and keep their action and message attachments.
Access: workspace members with edit access to each item. Errors: item not found or not editable.
setFilePublicLink
Turn a File Library file's public download link on or off. Access: workspace members who can change the file's sharing.
linkFileStoreNodeToProjects
Links a File Library item to at least one project; projectIds must not be empty. To use a file or folder as an AI proofing guideline on a project, call setProjectAiProofingGuidelineNodes instead.
unlinkFileStoreNodeFromProject
Removes one project link from a File Library item.
setProjectAiProofingGuidelineNodes
Replaces the File Library files/folders used as AI proofing guidelines on a project. They also apply to every sub-project. Send the full list: omitted nodes are removed. Access: requires non-read-only project access; newly added nodes must be visible to the caller. Errors: "Project not found" for a workspace mismatch; "File not found" for an inaccessible new node.
addFolder
Create a folder in the current workspace. For File Library (DAM) folders, pass type: fileStore. Root file-store folders default to Only me sharing unless nested under a parent folder (then sharing inherits from the parent). Notebook folders default to type notebook when type is omitted.
renameFolder
Rename an existing folder. For File Library (fileStore) folders, updates the folder path and descendant folder paths. Caller must have edit access on the folder.
deleteFolder
Delete or trash a folder. For File Library (fileStore) folders, trashes the folder subtree (folders and library files inside). For notebook and other folder types, marks the folder deleted and may cascade related cleanup. Returns true when the operation succeeds.
createForm
Creates a configured form that can create actions or projects or send email according to its targets. Match input elements to the data they collect. Resolve project IDs first; top-level projectId and actionsData.projectId must be 17-character alphanumeric IDs. The newProject sentinel is valid only when target includes action and project. Each creationConditions entry requires fieldId, comparisonOperator, and value. The number field type is unsupported. panel and paneldynamic containers require non-empty nested field arrays.
submitForm
Atomic form submission mutation. Determines internally whether to create actions, create a project, update a project, or send emails based on form.target. Each data.fields entry uses the existing form element name and an array of string values. Omit mapTo because the stored form definition supplies field mapping.
saveForm
Unified save mutation for creating or updating forms. If _id matches an existing form, updates it; otherwise creates a new one.
restoreFormVersion
Restore a saved form configuration as a draft, preserving the live published form. Access: Authenticated workspace members who may edit both the form and its draft. Errors: Missing form or saved version, insufficient access, or unavailable document files.
createGoal
Creates a Hive goal with owners, targets, dates, sharing, and optional action, project, or subgoal measurements. Progress display accepts null, number, or actions measurements; number display also accepts overdue, while status display requires status measurement. Actions and overdue use actions/projects units, number uses currency/custom/percentage, and status uses subGoals. Custom unit values may be caller-defined; other values and symbols must match their unit type. Ongoing, recurring, and fixed date modes are mutually exclusive; fixed requires both dates with startDate before endDate.
deleteGoal
Soft-deletes a Hive goal and removes it from active goal results. This does not archive Hive actions and is limited to the goal creator or a workspace admin. For bulk stale-goal cleanup, call getGoals first, list the targets, and delete only after the user confirms.
requestGoalUpdate
Asks a goal's owners (including members of owning teams) for a progress update by sending them a notification and activity item.
Access: any logged-in user. Errors: goal not found.
updateGoal
Updates a Hive goal. Display progress supports null, number, or actions measurements; display number also supports overdue; display status requires status measurement. Actions or overdue use actions/projects units, number uses currency/custom/percentage, and status uses subGoals. Unit values and symbols follow createGoal's rules. Ongoing, recurring, and fixed date-range modes are mutually exclusive; a fixed range requires startDate before endDate. Action and project IDs require their corresponding unit.
syncGoalFromWidget
Reads the scalar from the goal's sourceWidgetId widget (pivotNumbers, numbers or pivotTable) and writes it as the goal's currentValue. Each call records a goal metric history entry. Fails when the goal has no source widget or its source differs from expectedSourceWidgetId, when supplied.
scheduleGoalMetricSync
Creates a cron job that runs syncGoalFromWidget for the goal at dateTime and then on the repeatOn cadence. Replaces any existing schedule for the goal.
removeGoalMetricSync
Removes the goal's metric sync cron jobs. The goal keeps its sourceWidgetId.
upsertFieldDefs
Add or update fields (columns) on an existing Hive Table. Use for table schema changes; use createTables for a new table and updateRecordCells for row values. Access: Table editors, table creator, or workspace admins.
archiveFieldDefs
Archives table field definitions without deleting stored record values. Access: Table editors, table creator, or workspace admins.
createRecords
Creates multiple records in one Hive table. Returns row-level validation errors for records that could not be created.
upsertRecords
Create or update records by immutable integration identity.
updateRecordCells
Batch cell write — one or more records; grid paste is one round trip
deleteRecords
Soft-deletes records from one Hive table so they can be restored. Applies each relation field's configured onDelete behavior and returns an outcome for each requested record.
clearTableRecords
Soft-deletes a bounded page of active records, including rows hidden by row-level access. Access: Table creator or workspace admin. Errors: Missing table, workspace mismatch, campaign table, invalid cursor, or invalid limit.
linkRecords
Links related Hive table records. Repeating an existing link is idempotent.
insertThread
Returns the root message's existing thread or creates one. To reply, call insertMessage with the returned thread _id as containerId and containerType: group. Requires access to the root message's group chat.
insertGroup
Creates a Hive direct message, group chat, or thread for specified members and teams. For a direct message, members is the complete membership including the caller; exact membership is used to find and reuse an existing conversation. Requires access to the workspace.
adminCreateHighwayRun
Starts a Highway run from an administrator-supplied prompt. Access: Highway admin on secure VPN. Errors: unauthorized callers or unavailable control plane.
adminFollowUpHighwayRun
Sends a follow-up prompt to an active Highway run. Access: Highway admin on secure VPN. Errors: unauthorized callers, inactive run, or unavailable control plane.
adminSteerHighwayRun
Steers the active turn of a Highway run. Access: Highway admin on secure VPN. Errors: unauthorized callers, stale turn, or unavailable control plane.
adminCancelHighwayRun
Cancels an active Highway run. Access: Highway admin on secure VPN. Errors: unauthorized callers or unavailable control plane.
adminSetHighwayKillSwitch
Enables or disables Highway run submissions; enabling cancels active runs. Access: Highway admin on secure VPN. Errors: unauthorized callers or unavailable control plane.
configureAccountManagement
Turns Flywheel's proactive planning on or off for one account. Access: any user with CRM access to the account, while the workspace flag is on.
logAccountCallMailCall
Records the outcome of a call on a Flywheel call-mail row. Answered completes the row, a bad number fails it, and anything else leaves it waiting with the prepared email ready to send. Access: the rep the row belongs to.
emailNowForAccountCallMail
Sends the call-mail row's own mailbox draft now, because the call did not connect, and completes the row. Access: the rep the row belongs to.
updateFlywheelManagedMailbox
Register or unregister a Hive HQ member's mailbox for Flywheel operator-reviewed replies. Enabling clears flywheelAuto: registration never grants automatic sending. Does not change CRM ownership, connect a mailbox, or import historical mail. Access: Hive HQ operator — super admin with Hive HQ membership. Errors: Operator access denied; user is not a Hive HQ member.
adminWakeAccounts
Pulls each account's next check nearer, now. The operator-facing wrapper over the same
internal path the worker's wakeAccount takes, answering per account: woken, or why not.
An account a run already holds is refused rather than woken — a press there cannot pull its
alarm nearer and would only cancel the run in flight — and one that is switched off, unowned
or has nothing open is unavailable, as is one outside Hive HQ.
Access: Hive HQ operator — super admin with Hive HQ membership.
adminSetAccountNextCheck
Moves one account's next check, and writes the move into the same journal the machine's decisions use so the timeline reads continuously. Nearer is bounded by the run lease, the same floor a decision's own next check has: waking now is the wake's job. Fenced on the run revision — answers false when the run moved, and nothing is written. An account outside Hive HQ reads as not found. Access: Hive HQ operator — super admin with Hive HQ membership.
adminResolveFlywheelApproval
Approves or denies one tool call Flywheel's work paused on for an executor — a real person or
an Auto user — and resumes the run as that executor: the tool runs exactly as if they had
answered it. The operator is
written into the account's journal before the hand-off, as the approval's one line, so a lost
reply never loses who answered a call that ran. An answer to an approval another answer is
already under way for reads as not found. A hand-off that fails keeps the line, marked
"(not confirmed)", and holds the approval for ten minutes, until the failed attempt can no
longer land; after that it can be answered again while its thread still waits on it.
Only an approval accountFlywheelApprovals would list can be answered: anything else reads
as not found.
Access: Hive HQ operator — super admin with Hive HQ membership.
updateCrmAccountMemory
Save an editable account-memory version while preserving its evidence references. Access: account CRM and contributing-source access. Errors: stale revision or invalid content.
restoreCrmAccountMemory
Restore a historical body and its evidence as a new memory revision. Access: account CRM and historical-source access. Errors: missing or stale revision.
createCrmAssociation
Creates or upserts a CRM association. For Buzz and automation: after createOpportunity from an action context, either pass linkToActionId on the opportunity input or call this with linked_action and opportunity as fromObject fields and Hive action as toObject fields so the action CRM panel and opportunity activity surfaces show the durable link.
setProjectAccountLinks
Replaces the account links for a project. Access: requires non-read-only access to the project. Errors: standard authentication and project access errors.
setAccountProofingGuidelineDocuments
Replaces the proofing guideline file links for an account. Access: requires access to the account. Errors: standard authentication and account access errors.
deleteCrmAssociation
Soft-deletes a CrmAssociation by id. Idempotent: returns false when the association is already deleted or not found, true when a row was soft- deleted. Access: requires workspace access to the association's workspace. Errors: none beyond the standard workspace access assertion.
deleteCrmRecords
Soft-archives CRM records of one type; pass one ID for a single record. Records remain recoverable. Resolve IDs first and call only for an explicit archive, delete, or remove request; do not use it to close an opportunity—use closeOpportunity instead. Requires CRM access. Account batches fail when live child accounts exist outside the batch. Returns the archived-record count.
restoreCrmRecords
Bulk restore previously soft-deleted CRM records of one type. Returns the number of records restored.
Access: Workspace members with CRM access.
mergeCrmRecords
Merge two CRM records of the same type. The duplicate's associations, foreign-key references, and blank field values move onto the survivor (survivor's values always win), then the duplicate is archived. Only account and person records can be merged today. An already-archived duplicate is accepted so an interrupted merge can be re-run to completion.
Access: Workspace members with CRM access.
Errors: Throws if the user lacks CRM access, the survivor is missing or archived, the duplicate is missing, the two ids are identical, an account merge would create a hierarchy cycle, or Salesforce sync would be broken (both accounts linked, or only the record being archived is linked).
updateCrmRecordsOwner
Bulk reassign the owner of CRM records of one type. Passing null clears owners. Returns the number of records updated.
Access: Workspace members with CRM access.
logCall
Logs a standalone CRM call (from the Twilio dialer, or entered by hand from a contact, account, or opportunity page) and links it to the provided person, account, and opportunity via linked_call associations. Access: Workspace members with CRM access. Errors: Throws when no person, account, or opportunity is provided.
updateCrmCall
Changes a call that was logged by hand and keeps its person and opportunity links in step. The call's account links stay; their date and direction follow the call. Access: Workspace members with CRM access. Errors: Throws when the call is not hand-logged, or when no person, account, or opportunity stays linked.
deleteCrmCall
Deletes a call that was logged by hand and removes its links. Access: Workspace members with CRM access. Errors: Throws when the call is not hand-logged.
updateCrmWorkspaceMemory
Replaces the workspace's CRM rules. Workspace admins only.
startCampaignAudienceSession
Open the campaign owner's visible audience conversation. Access: build starter with Buzz access.
updateCampaignAudiencePipeline
Configure, run, retry or stop the original audience pipeline, or add people to a finished web-search audience: expand with targetPeopleCount adds that many more people, as the table's Add people does. Access: build starter; expand needs CRM access only. Errors: stale run or invalid stage.
approveCampaignAudiencePipeline
Approve exact recipients from a current completed preview. Access: build starter. Does not send or prepare email.
startCampaignBuild
Starts LLM-assisted campaign creation from a freeform campaign brief. Creates a draft for build and review; it does not execute the campaign or send email. A later recipient-persistence step requires explicit audience confirmation. Access: caller must be a non-external member of the workspace. Errors: invalid or unauthorized workspace access is rejected.
createCampaignFromGoal
Creates a campaign and its audience table from one goal sentence and returns at once, then builds the audience in the background: Buzz names the campaign, designs the audience, picks one person per account, and lands them as table rows with a fit score and the reason they were picked. Poll getCampaign and read tableBuild.stage for progress. Does not send email. With autoContinue, the build runs every step without stopping and answers its own questions with its best guesses; otherwise it stops after each step for continueCampaignBuild. To follow up with people an existing campaign already emailed, use addCampaignFollowUp on that campaign. Access: caller must be a non-external member of the workspace. Errors: empty goal or unauthorized workspace access is rejected.
addCampaignPeopleList
Adds a pasted list of names and emails to the campaign's table as rows with planned recipients. CRM contacts link to their person; other emails become rows without a CRM record. Every entry must resolve first (preview with previewCampaignPeopleList). People who already have a row are skipped. Added people join an approved audience; before the audience pipeline has run, they become the approved audience. Does not send email. Access: caller must have CRM access to the campaign workspace. Errors: a live build, or a list with unresolved, ambiguous or invalid entries, is rejected.
confirmCampaignAudience
Persists the exact campaign accounts or people explicitly selected for an in-progress campaign build. It does not send campaign email. Access: caller must have access to the campaign workspace. Errors: missing campaign or unauthorized workspace access is rejected.
createCampaign
Creates a draft CRM campaign. To follow up with people an existing campaign already emailed, use addCampaignFollowUp on that campaign.
updateCampaign
Updates campaign planning, status, or custom fields after a real outcome.
designCampaignAudience
Regenerates a campaign audience definition from a follow-up design prompt. Access: caller must have access to the campaign workspace. Errors: missing campaign or unauthorized workspace access is rejected.
autoSelectCampaignRecipients
Selects and persists up to the campaign's target count of recipients after the audience preview is explicitly confirmed, choosing at most one objective-fit person per account and skipping accounts without a credible match. Requires campaign-workspace access and an existing audience definition; missing, unauthorized, or unconfirmed campaigns are rejected. Does not send.
proposeCampaignRecipientStrategies
Proposes and persists a play strategy for each active campaign recipient.
prepareCampaignRecipientPlans
Starts asynchronous drafting for selected campaign recipients and returns immediately. Recipient status progresses from queued to drafting, then to a persisted plan or failed; this does not send campaign email. Poll getCampaignRecipients until no selected recipient is queued or drafting. Finished drafts are reviewed and sent from the campaign Queue.
executeCampaign
Starts execution for approved campaign recipient plans, including queued email sends. Before sending email, obtain explicit user consent for the sender, recipients and reviewed content. If consent is missing or there is any doubt about approval or scope, ask the user for explicit approval and wait for their answer before calling this tool. Approval to create or draft a campaign is not consent to send. Use recipientIds to scope a cohort; omitted recipientIds selects eligible planned recipients. An empty list is rejected. Returns before delivery: use getCampaignRecipients to read persisted play status and delivery evidence. Access: workspace members with CRM and Buzz access; email plans must be assigned to the caller. Errors: inactive campaign, unauthorized access, missing plans, or no eligible recipients.
ensureCampaignTable
Returns the campaign's audience table, creating it with the standard person columns when the campaign has none yet. Idempotent. Access: caller must have CRM access to the campaign workspace. Errors: missing campaign or unauthorized workspace access is rejected.
addCampaignCrmColumn
Adds a CRM field (from getCampaignCrmColumnOptions) as a read-only campaign table column, filled from each row's person or account. A field that is already a column is returned unchanged. Access: caller must have CRM access to the campaign workspace. Errors: missing campaign or table, or a field the workspace does not have.
refreshCampaignCrmColumns
Brings the campaign table's CRM columns in step with the CRM, writing only cells that changed. Without force it runs at most once an hour per table and otherwise skips. Access: caller must have CRM access to the campaign workspace.
reportCampaignBuildProgress
Reports the hidden Buzz thread's criteria design for a campaign AI add run. Only the thread recorded on campaign.tableBuild may report; threadId is injected by Buzz from the session and must match. Accepted: stage finding_people with the final audience definition (hands the run to the server, which creates the criteria column and adds people), or stage failed with an error while the run is still planning. Does not send email. Access: the user who started the run. Errors: missing campaign, a thread that does not own the run, or an invalid definition.
startCampaignFromAccount
Creates a staged campaign seeded from an account (optionally its won opportunity) and asks Buzz to draft the win profile. The campaign's audience source is prospect_discovery; the builder's audience step shows the profile for review once the worker reports back. Access: caller must have CRM access and the workspace must have the crmProspectDiscovery feature enabled.
updateCampaignDiscoveryProfile
Stores the rep's edits to the win profile (and, when given, the search budget) and parks the campaign in awaiting_review. Rejected while a discovery step is still running.
runCampaignDiscoverySearch
Runs the People Data Labs company + person search for the reviewed profile. The seed account's domains and every candidate the rep already imported or dismissed on this campaign are excluded. Requires a reviewed profile; rejected while a step is still running.
retryCampaignDiscoveryProfile
Retries a failed initial profile on the same campaign using freshly authorized seed context.
importCampaignDiscoveryCandidates
Brings the chosen organizations into the CRM as prospect accounts with their contacts as people (existing domains and emails link instead of duplicating), adds the accounts to the campaign audience, and marks the candidates imported. Already imported or dismissed ids are ignored.
dismissCampaignDiscoveryCandidates
Marks suggested candidates dismissed; their domains are excluded from later searches.
updateCampaignPilot
Configure the campaign writing brief, add pilot-only research or presentation columns, define explicitly requested research criteria, refresh one column, or draft the first email. Requires caller-owned pilot and matching revision. Never prepares other recipients or sends email.
addCampaignResearchColumn
Adds an AI research column to the campaign table. With researchExisting (default true) it queues research for every person already in the table; people added later are researched only when their add asks for it. Each person's research uses Buzz AI credits. With lookbackDays, only evidence from that many days before each run counts, so a rerun refreshes the column (for example recent news). With webSearch, the prompt is an open-ended request Buzz answers by searching the public web for each person, such as their talks, publications or published content; the cell sums up what it found and the details list each asset with its link. It runs a few people at a time. Access: caller must have CRM access to the campaign workspace. Errors: missing campaign, empty label or prompt, a lookbackDays other than 30, 90 or 180, exhausted Buzz AI credits, or rate limit.
addCampaignDeckColumn
Adds a presentation column. With template any_topic (default), each deck is a workspace-branded presentation for the requested topic and audience. With template outreach, each deck uses fixed outreach slides built from the person's research in their organization's branding, and the prompt is the pitch: the offer, the proof line Buzz may use, and the ask. Decks use the brief, relevant readable columns on each recipient row and authorized uploaded documents, including documents in row attachment cells. Every rendered slide is reviewed and repaired before a private PDF and editable HTML are saved. Accepted PDFs accompany new email drafts. With generateExisting (default true), queues existing people; later people get a deck when their add fills AI columns. Each deck uses Buzz AI credits. Access: caller must have CRM access to the campaign workspace. Errors: missing campaign, empty label or prompt, a slideCount outside the template's range, an example that is not a readable PDF or not for an outreach deck, exhausted Buzz AI credits, or rate limit.
rerunCampaignResearch
Fills or refreshes AI columns: research columns, presentation columns, and research on criteria columns that already hold a metrics score, for the given rows or every row. With onlyMissing, only cells with no result, a failed result or a cancelled one. Rows already queued or running are left alone. Access: caller must have CRM access to the campaign workspace. Errors: missing campaign, unknown column, exhausted Buzz AI credits, or rate limit.
importCampaignDeck
Puts a finished presentation PDF made outside Hive into one person's presentation cell. The cell becomes done with the PDF, which accompanies the person's email drafts like a generated deck and is shared with the workspace so any teammate can send it. Buzz's fact and design review does not run; the cell records who imported it. Re-importing replaces the cell's PDF, and a presentation queued or being generated for the cell is dropped. Uses no Buzz AI credits. Access: caller must have CRM access to the campaign workspace and own the uploaded files. Errors: missing campaign, a column that is not a presentation column, a row that is not a person in the campaign table, or a file that is not the caller's finished PDF (or HTML source) in this workspace or is already another person's or campaign's deck.
cancelCampaignResearch
Stops research on the campaign: all AI columns or the given ones, every row or the given rows. Queued research is cancelled. Running web search research writes up what it found and keeps it as an unfinished report that Continue research resumes; other running research is cancelled. Cells keep the value they had. Access: the user who queued it, workspace admins, or table managers.
releaseCampaignOutreachHold
Releases a person held from outreach because research scored them at or below 10. Their campaign recipient returns to planned. Access: caller must have CRM access to the campaign workspace.
draftCampaignEmailsForRows
Drafts campaign emails for the people in the given table rows. Each draft is written for the campaign's goal and personalised with what the table knows about the person: their Campaign Score with the metrics and research behind it, and their research columns. Rows without a campaign recipient get a planned one first. Rows for people held from outreach, without an email, or already drafting are skipped and reported. Nothing is sent: drafts wait in the campaign's Emails tab. Access: caller must have CRM access to the campaign workspace. emailTemplate and emailRules are alternative drafting methods. Passing one saves it and clears the other; every draft then follows the selected method. followUps sets the campaign's sequence first: the follow-up steps after the first email, in order, each with its wait and its own writing brief. Each person's email for every step is then drafted with their first email, the same way, and reviewed with it in the Emails tab. Launching a person's first email approves their follow-ups; each goes as a reply in the same thread once its wait has passed, on a weekday, and none goes after the person replies, books a meeting, opts out or bounces. Steps left out of followUps are deleted (sends that went out stay); [] removes them all; omit followUps to keep the current steps, which are drafted too. With senderMode (self or account_owners), it is saved as the campaign's emailSenderMode first. Drafts send from the campaign's emailSenderMode: account_owners sends each from the owner of the person's account, who reviews and sends it; anyone else sends from the caller. Errors: missing campaign, no table, more than 100 rows, fixed_user as senderMode, exhausted Buzz AI credits, more than 10 follow-up steps, an unknown followUpId, a delay outside 1 to 60, or a step without generationInstructions.
findCampaignPeople
Starts an AI add run in the background and returns at once: reuses a criteria column or designs new criteria, scores every eligible account, picks one person per account in rank order, and adds them as rows with their score (research then tweaks scores for metrics_research criteria). People already in the table are skipped. Poll getCampaign and read tableBuild. Does not send email. Access: caller must have CRM access; pdl also needs the crmProspectDiscovery feature. Errors: a run already live, missing campaign, invalid criteria input, or unauthorized access.
upsertCampaignRecipientPlan
Adds one CRM person to a campaign, or updates their existing selection and draft plan. Repeated calls for the same workspace, campaign, and person update the same live recipient. Binds the person's linked CRM account and resolves email sender from campaign settings. Existing sender snapshots are preserved when updating content. This does not send email. Resolve a person ID with getPersons or upsertPersonsByEmail first. Access: workspace members with CRM access. Errors: campaign or person not found; invalid sender; additional attendee not a workspace member.
upsertCampaignRecipientPlans
Batch form of upsertCampaignRecipientPlan: adds, suppresses, or excludes many campaign recipients in one call, keyed by workspace, campaign, and person, with optional strategy and execution plan.
Access: CRM access in every workspace named by the inputs. Errors: campaign or person not found; additional attendee not a workspace member.
updateCampaignRecipientExecution
Executor-side mutation: record actual recipient lifecycle progress after tool results or deliberate non-intervention. Do not use this mutation to request approval; call the real side-effect tool and let the approval queue set awaiting_approval when it pauses. An operator may stop execution with status failed and outcome manually_stopped, omitting campaignId and executionThreadId. Access: current CRM access plus campaign ownership or execution ownership. The current run is cancelled before the stop is recorded; cancellation failures preserve the claim for retry.
deleteCampaignRecipient
Removes one person from a campaign by soft-deleting their campaign recipient. Live execution is cancelled before removal; cancellation failures preserve the recipient. Existing delivery history and the CRM person are retained. Returns false when already removed. Access: workspace members with CRM access; live execution also requires campaign or execution ownership. Errors: unauthorized access, failed cancellation, or a changed execution claim.
deleteCampaignRecipients
Removes campaign recipients, retaining their delivery history and CRM people. Live executions are cancelled before removal; a cancellation failure leaves that recipient intact. Access: CRM access in every recipient workspace; live execution requires campaign or execution ownership. Errors: unauthorized access, failed cancellation, or a changed execution claim. Earlier recipients may already be removed if a later removal fails; read membership before retrying.
updateCampaignRecipientPlay
Updates an unlaunched Campaign play draft. Access: caller must have CRM access to the Campaign workspace. Errors: missing, launched, or unauthorized plays are rejected.
setCampaignRecipientPlays
Replaces unlaunched plays selected for one Campaign recipient. Access: caller must have CRM access to the Campaign workspace. Errors: empty, unsupported, or ineligible modal selections are rejected.
regenerateCampaignRecipientPlay
Requeues drafting for one Campaign play. Access: caller must have CRM access to the Campaign workspace. Errors: missing, launched, or unauthorized plays are rejected.
reassignCampaignEmailSender
Moves drafted Campaign emails to another sender, who reviews and sends them from their own mailbox. Each draft is signed again for the new sender, and the new sender is notified. Nothing is sent. Access: Campaign owner or workspace admin. Errors: a launched, sent or still drafting email, an email offering a meeting time from its current sender's calendar, or a sender who is not a workspace member with CRM access.
setCampaignRepliesHandled
Marks Campaign replies handled, or back to needing an answer, for the whole team. Handled replies leave the Campaign's unhandled reply count. Access: caller must have CRM access to the Campaign workspace. Errors: Campaign not found, or more than 500 recipients.
replyToCampaignReply
Answers a Campaign reply from the mailbox the Campaign email was sent from, in the same thread, signed by that mailbox, and marks the reply handled. Access: the sender, or a member the sender named a send delegate, with CRM access. Errors: reply not found, empty or too long body, caller is not the sender or a delegate, sender mailbox disconnected, or thread no longer in the mailbox.
launchCampaignRecipientPlay
Launches one reviewed Campaign play. For generate_email, this queues sending the saved email draft through the campaign's assigned sender. A launched status means queued, not delivered; read getCampaignRecipients plays and delivery to verify the result. Repeated launches of an already launched or delivered play are rejected. An email with a future executionPlan.scheduledSendAt keeps it; otherwise it takes its sender's next slot in the campaign, 18 seconds after the last (200 an hour), unless sendNow is true. Before sending email, obtain explicit user consent for the sender, recipients and reviewed content. If consent is missing or there is any doubt about approval or scope, ask the user for explicit approval and wait for their answer before calling this tool. Approval to create or draft a campaign is not consent to send. Access: an email play only by its assigned sender, who needs a connected mailbox; other plays by the Campaign owner or a Campaign workspace admin. Errors: missing content, invalid target membership, or unauthorized launch is rejected, as is a play changed since expectedModifiedAt.
unscheduleCampaignEmail
Cancels a scheduled campaign email before its send time and returns it to an unsent draft with no send time. To edit or reschedule it, call this, then updateCampaignRecipientPlay with the new content and executionPlan.scheduledSendAt (null sends at once), then launchCampaignRecipientPlay. Recipients without plays are re-planned with upsertCampaignRecipientPlan and executeCampaign. Access: Campaign owner, workspace admin, or the email's assigned sender. Errors: rejected once the email has started sending or when it was never scheduled.
scheduleCampaignSends
Sets each planned campaign email to send at the chosen local time in its recipient's timezone, spaced by the stagger per sender within a timezone. The timezone comes from timezoneOverrides, the recipient's own timezone or their account's state. Otherwise Hive guesses from the campaign row's location, or the contiguous US: a state split across zones gives each of its zones, and the email sends by the first. Run with dryRun true first to review every time; it writes nothing. This does not send: executeCampaign still needs the sender's approval, and a time already past is returned unresolved. With meetingSlots, each email's {{meetingSlot}} or {{SLOT}} is replaced by a free sender slot that at most five emails offer across campaigns and that suits every zone the recipient may be in. An email with no slot, or whose recipient may be outside the US, is returned unresolved with no send time. Access: campaign owner, workspace admin, or the email's assigned sender. Errors: missing campaign, malformed day, time or stagger, or an override that is not an IANA timezone.
addCampaignFollowUp
Adds a follow-up step to an existing campaign. The step sends automatically: each person who got the campaign's email and has not replied, opted out or bounced gets the body as a reply in their original thread, delayAmount delayUnit after the last campaign email they got. Saving it is the approval to send, so confirm the body and timing with the user first. Following up with people a campaign already emailed is a step on that campaign. With emailRules instead of a body, the step is drafted per person like the first email: Draft emails (draftCampaignEmailsForRows) writes each person's email for it together with their first email, and launching that first email approves it. To set up a whole sequence before drafting, prefer draftCampaignEmailsForRows' followUps. A person drafted before the step existed waits on it until their emails are drafted again. Access: caller must have CRM access to the campaign workspace. For a body, the caller must also be the sender of the campaign email of every person the step goes to, or a send delegate of that sender (the rule for launching campaign emails). A person who joins later gets the step only if their sender, or a send delegate of that sender, last approved it; otherwise their send fails. Errors: missing campaign, both or neither of body and emailRules, emailRules without generationInstructions, an empty body or one over 5000 characters of HTML, a delay outside 1 to 60, a campaign that already has 10 follow-up steps, or, for a body, a caller who is not the sender or a send delegate for everyone the step goes to.
updateCampaignFollowUp
Edits a follow-up step's timing or body, or pauses and resumes it. Sends that already went out stay as they are. A new body or delay, or a resume, approves the step's sends again. Access: caller must have CRM access to the campaign workspace. To change the body or delay, or to resume, the caller must also be the sender of the campaign email of every person the step still goes to, or a send delegate of that sender, as for addCampaignFollowUp. Anyone with CRM access may pause. Errors: missing campaign or step, an empty body or one over 5000 characters of HTML, a delay outside 1 to 60, or a caller who is not the sender or a send delegate for everyone the step still goes to.
deleteCampaignFollowUp
Deletes a follow-up step. Its sends that have not gone out are dropped; sent ones stay. Access: caller must have CRM access to the campaign workspace. Errors: missing campaign or step.
updateCampaignFollowUpRecipients
Skips people for one follow-up step before it sends to them, or undoes a manual skip. People the step already went to, or is sending to, are left as they are. Access: caller must have CRM access to the campaign workspace. Errors: missing campaign or step, more than 500 people, or undoing a skip after a later step reached the person.
setCampaignSequence
Sets the campaign's sequence: every campaign is a sequence whose Step 1 is the first email (its brief is the campaign's emailRules) and whose later steps are these followUps, in order, each with its wait after the email before it and its own writing brief. Listed followUpIds keep their step; brief steps left out are deleted (sends that went out stay); [] leaves only Step 1 and any steps with a fixed body, which keep their place (delete those with deleteCampaignFollowUp). Nothing is drafted or sent: each person's drafts of the steps are written with their first email the next time it is drafted (prepareCampaignRecipientPlans, draftCampaignEmailsForRows or the pilot), and go out, as replies in the same thread and only until the person replies, after their first email launches. People already emailed are not redrafted: write each of their steps with updateCampaignRecipientFollowUpDraft, or their steps never send. Confirm the steps and waits with the user first. Access: caller must have CRM access to the campaign workspace. Errors: missing campaign, more than 10 steps, an unknown followUpId, a wait outside 1 to 60, or a step without generationInstructions.
updateCampaignRecipientFollowUpDraft
Edits one person's draft of a follow-up step that has emailRules, before the step went to them. It must keep the step's emailRules. Once their first email launched or went out, the edit approves their drafts, so confirm the text with the user first. This is how a person emailed before the campaign had steps gets each step's draft: write it from their full row and the email they were sent. Access: caller must have CRM access to the campaign workspace; after launch, the caller must also be the person's sender or a send delegate of that sender. Errors: missing person, step or draft body, a step without emailRules, a step already sent to the person, broken step rules, or a caller who may not approve the sender's emails.
setPersonPrimaryAccount
Sets (or clears) a person's primary CRM account link. Pass a null accountId to remove the primary account. Enforces a single primary account per person. Access: workspace members with CRM access to the person.
updatePersonAttribution
Updates native person attribution from any integration. Existing original attribution is protected unless overrideOriginalSource is explicitly true. Omitted sources stay unchanged. Access: authenticated workspace members with CRM access to the person. Errors: rejects inaccessible people, missing source snapshots and invalid attribution dates.
upsertPersonsByEmail
Creates or updates CRM people, matching existing people by email address.
importCrmCsvRows
Imports CRM accounts, contacts, and opportunities from CSV row data. Access: Workspace members with CRM access. Errors: Returns validation errors for invalid row data and throws if user lacks CRM access. requireDomain: attach people to accounts by domain only (the row's domain, else the contact's work email domain; never by name). Any row with no usable domain (NEEDS_DOMAIN), a domain two accounts share (AMBIGUOUS_DOMAIN) or a contact with another primary account (PRIMARY_ACCOUNT_CONFLICT) comes back as an error and nothing is written.
unlinkCrmMeetings
Removes CRM links from meetings the caller can read, without hiding calendar meetings. The person who logged a meeting (for a calendar meeting: its organizer or an attendee) or a workspace admin removes all of its links, and a manually logged meeting is then soft-deleted along with its meeting user data. Anyone else removes only the links they added themselves; links someone else added, or that were created automatically, are kept. Returns the number of distinct meetings with links removed or manually logged meetings deleted. Use unlinkCrmMeetingsWithCounts to also learn how many links were kept. Access: Workspace members with CRM access.
unlinkCrmMeetingsWithCounts
Same as unlinkCrmMeetings, reporting how many links were removed and how many were kept because someone else (or an automatic process) added them. Access: Workspace members with CRM access.
updateMeetingFollowUpDraftSettings
Enable or disable auto-drafting follow-up emails after CRM-linked calls. Access: workspace admins with Hive CRM enabled.
setMeetingFollowUpDraftEnabled
Compatibility API for clients that still manage the retired workflow.
resetMeetingFollowUpDraftWorkflow
Compatibility API for clients that still manage the retired workflow.
exportCrmTableCsv
Exports CRM table rows to CSV using the same server-side filters, search, and sort state as the list views. Access: Workspace members with CRM access. Errors: Throws if user lacks CRM access or the export entity type is not supported.
saveCrmTableSavedView
Creates or replaces a named CRM table view for the current user. Access: Workspace members with CRM access.
deleteCrmTableSavedView
Soft-deletes a CRM table saved view owned by the current user. Access: Workspace members with CRM access.
createResourcingSavedView
Creates a named saved view owned by the caller. Access: workspace members. Errors: throws when the name is empty after sanitization or longer than the stored bound, when the caller already has a view of that name on this surface, when sharingType is anything other than 'me' or 'everyone', or when surface is userDirectory and directoryFilters is omitted.
updateResourcingSavedView
Renames a saved view, replaces its filter state, or both. Access: the view's creator. Errors: throws when the view is missing, the caller is not its creator, the input carries neither field, or the new name is empty, over the stored bound, or already taken on this surface.
createCrmForm
Creates a CRM form and returns it with its public form id. Access: workspace members with CRM access. Errors: missing name and unauthorized CRM access are rejected.
updateCrmForm
Updates an existing CRM form. Access: workspace members with CRM access to the form's workspace. Errors: unknown forms and unauthorized CRM access are rejected.
deleteCrmForm
Soft-deletes a CRM form. Access: workspace members with CRM access to the form's workspace. Errors: unknown forms and unauthorized CRM access are rejected.
createProjectBudgetVersion
Cut a budget baseline. Returns it approved when no approval rule matched, and pending — held on the matched rule's route, with the plan untouched and still editable — when one did.
approveProjectBudgetVersion
Clear one step of the route holding a baseline. The baseline is numbered, supersedes the live one and locks the plan onto itself as the last step clears; until then it stays pending on the next approver.
rejectProjectBudgetVersion
Refuse a held baseline. Terminal, and the plan is left exactly as it was — cut again instead.
createAdvanceBilling
Issues an advance bill and posts it: Dr accounts receivable / Cr the chosen deferred revenue account, so money billed ahead of the work is on the trial balance from the day it is billed. The document's deferred revenue schedule and the recognition schedule that relieves it are created with it, in the same transaction as the journal. Access: signed-in members of the workspace with the billingInvoiceGenerate permission, in a workspace where finance is enabled. Errors: amount not greater than zero; schedule periods not greater than zero; deferred revenue account is not an active other current liability account; revenue account is not an active income account; no receivable or revenue account mapped for the workspace; issue date inside closed books; and a refusal to post at all when the deployment cannot run the write in a transaction, which keeps the document and its journal together. Not validated, and so not listed: the client account, the project and the invoice are stored as given. The pickers that author them offer only what this workspace holds, which is where that is decided today.
applyAdvanceBilling
Applies an advance bill to a posted customer invoice: Dr the deferred revenue account / Cr accounts receivable, relieving the deferral against the receivable that invoice raised and reducing the invoice balance. Revenue is recognized by the invoice, so nothing is credited to revenue here — the application draws from the same deferred pool the recognition schedule draws from, and the recognition periods it consumes are reduced by the same amounts. Access: signed-in members of the advance billing's workspace with the billingInvoiceGenerate permission, in a workspace where finance is enabled. Errors: advance billing not found; the advance bill posted no issuance journal, so the deferral this would relieve was never credited; amount not greater than zero; amount above the unapplied balance; amount above the deferred revenue still held (revenue already recognized cannot be deferred again); source is not a posted customer invoice; invoice belongs to another customer; accounting period not found or not open; posting batch not found; posting date inside closed books; the advance billing, its invoice, or one of its recognition periods changed while it was being applied; and a refusal to post at all when the deployment cannot run the write in a transaction. Repeating a call with the same idempotencyKey returns the first result.
closeAdvanceBilling
Drafts the revenue invoice that closes out an advance bill's unapplied balance, in one call instead of hand-authoring it. The draft goes through the same writer every generated invoice uses, so it is freely editable, never auto-sent, and each line carries the derivation an adjustment receipt is a diff against. It posts nothing: the deferral is relieved when a human posts the draft and applies the advance to it, which is the existing two-step rail. The close line credits the revenue account the advance bill stamped at issuance — the one its recognition schedule credits — so closing cannot recognize a single deferral into two accounts. Naming an item overrides that at posting, since an item states where its own revenue is earned. Access: signed-in members of the advance billing's workspace with the billingInvoiceGenerate permission, in a workspace where finance is enabled. Errors: advance billing not found; the member may not write the books the advance bill is filed in; the advance bill posted no issuance journal, so the application this draft exists for could never relieve it; nothing left unapplied; the advance bill is billed in a currency the draft-invoice rail cannot total; and a live closing draft already exists — post, edit or void it first, which is what stops the same deferred balance being asked for twice.
updateSetupSection
Updates the status, owner, or note for a finance setup section.
assignFinanceOwnerReviewer
Assigns an owner and reviewer to a finance record.
bulkSubmitFinanceRecords
Submits the selected finance records for review.
bulkApproveFinanceRecords
Approves the selected finance records.
bulkPostFinanceRecords
Posts the selected finance records to the ledger.
bulkAssignFinanceOwnerReviewer
Assigns an owner and reviewer to the selected finance records.
bulkChangeFinanceRecordStatus
Changes the status of the selected finance records.
bulkVoidCancelFinanceRecords
Voids or cancels the selected finance records.
saveFinanceReportSavedView
Store a report view for the calling reader, and answer with every view they now hold.
The list rather than the stored view alone, because the list is what the caller's filter bar picks from: a caller handed only the view it just wrote still has to ask for the list, and that second question is the one this contract exists to remove. Asked after the write, on the same round trip, it cannot answer from before it. Access: members of the workspace, in a workspace where finance is enabled. Errors: the name or report is empty, the workspace is not found, finance is disabled for it, or the caller is not a member.
deleteFinanceReportSavedView
Remove one of the calling reader's report views, and answer with every view they still hold.
The same list the save answers with, for the same reason. It replaces a boolean that said only that something had happened, leaving the caller to ask what it had been left with. Access: the reader who stored the view, in a workspace where finance is enabled. Errors: the view is not found or was stored by someone else, or finance is disabled for its workspace.
exportFinanceReportXlsx
Exports a finance report as an Excel workbook.
exportFinanceTableRecords
Exports records from a selected finance table.
updateFinanceEmployeeProfile
Updates an employee profile used by Finance.
upsertDocumentNumberSequence
Creates or updates a finance document-number sequence.
promoteProjectTemplate
Legacy alias rejected because project templates are now managed through native Projects.
publishProjectTemplate
Legacy alias rejected because project templates are now managed through native Projects.
updatePurchaseOrderPaymentTerm
Updates the payment term on a draft or rejected purchase order. Access: purchasing create permission in the order's workspace. Errors: refuses a missing or non-editable order, or a term that is inactive or belongs to another workspace.
updateFinancePurchaseOrderLine
Updates a line on a draft purchase order.
submitPurchaseOrder
Sends a draft purchase order for approval. Evaluates the workspace's approval rules and, when one matches, records its route on the order so approval consumes the steps in sequence. Access: 'purchasingCreate' in a workspace where finance is enabled. Errors: refuses an order that is not draft or has no lines, and refuses a non-positive total.
approvePurchaseOrder
Approves a submitted purchase order, or clears one step of the rule route holding it. With a matched route, each call consumes the step the order is waiting on; the order reaches 'approved' — committing budget cost entries — only as the last step clears. Without a route the first call approves outright, exactly as before rules were enforced. Access: 'purchasingApprove' in a workspace where finance is enabled. A rule route can require more than that permission, never less: a step naming a user or team admits only them. Errors: refuses an order that is not submitted, and refuses a user the route is not waiting on.
rejectPurchaseOrder
Rejects a submitted purchase order at the approver's decision point. Distinct from cancelling: reject is the approver's answer before approval, leaving the order at 'rejected' for its owner to revise and resubmit. Any rule route holding the order closes with it, so a rejected order never reads as still mid-route. Access: 'purchasingApprove' in a workspace where finance is enabled, and — when a rule route is holding the order — only the approver that route is waiting on. Errors: refuses an order that is not submitted, and refuses a missing or blank reason.
closePurchaseOrder
Closes an approved purchase order that will take no further vendor bills. The relief path for a prebilled cost accrual whose vendor invoice never arrives: the accrual is reversed on the closing date, and the order's open commitments and committed cost entries close with it. Distinct from cancelling, which ends an order that should not have been placed. Access: 'purchasingApprove' in a workspace where finance is enabled. Errors: refuses an order that is not approved, and refuses a missing or blank reason. Closing an already-closed order returns it unchanged.
unapprovePurchaseOrder
Takes back an approval so the order can be revised, returning it to 'draft' and incrementing its revision. The unlock half of the approval lock: approving is what freezes an order's lines, so unapproving is what thaws them, and resubmitting builds a fresh rule route against the revised total. The committed cost entries the approval emitted are reversed, because an order back in draft commits nothing. Distinct from reject, which is the approver's answer before approval, and from close and cancel, which end the order. Access: 'purchasingApprove' in a workspace where finance is enabled. Errors: refuses an order that is not approved, and refuses a missing or blank reason. Refuses an order anything has already arrived against — a linked vendor bill, a recorded receipt, or an open prebilled cost accrual — because revising the lines those reference would strand them.
recordPurchaseOrderReceipt
Records receipt of goods or services against a purchase order.
createVendorBillFromPurchaseOrder
Creates a vendor bill from a purchase order.
approveVendorBillPayable
Approves the vendor bill payable linked to a purchase order.
markVendorBillReadyForPayment
Marks the linked vendor bill as ready for payment.
createVendorPayment
Records in the Hive ledger a vendor payment that was made outside Hive (check, ACH, wire). Does not move money, contact a bank or pay anyone; it is bookkeeping only. This is the AP mirror of createReceipt. The bill is whichever target the input names: a purchase-order bill link, or a bill document. One verb serves both, so there is one set of period gates, idempotency guards and void paths to keep in step. Writes a FinanceVendorPayment allocated to the bill, posts Dr A/P (under the bill's identity, so the AP subledger and aging follow it) / Cr the payment account, and advances the settled bill. Access: 'accountingPost' in a workspace where finance is enabled. Errors: refuses an unposted bill, a link not marked ready for payment, an amount above what the bill still owes, and a payment in another currency. Passing idempotencyKey makes it safe to retry.
voidVendorPayment
Reverses, in the Hive ledger only, a vendor payment record by writing the offsetting payment that cancels it, and returns that offsetting document. Does not recall, cancel or refund any real payment. The void is a document, not a status: it carries the negative of the original's amount and allocations under the original's number suffixed '-VOID', and posts a reversing journal through the shared reversal builder, so every AP read that sums payments over a window — 1099 detail, cash-basis P&L, AP aging — nets it out without being taught about voids. The bills the original settled are reopened to what they owed before it, which is what makes them payable again; the original payment stays posted and is stamped with the void. Access: 'accountingPost' in a workspace where finance is enabled — the void posts a document rather than unposting one, and is the same authority that recorded the payment. Errors: refuses a payment with no journal of ours (a synced payment), one already voided, the offsetting document itself, an empty reason, and a void into a closed period.
createVendorPaymentRun
Builds a draft worksheet of vendor bills to record as paid: every bill ready for payment, grouped into one payment record per vendor, priced at each bill's outstanding balance. Writes nothing to the ledger and does not move money — the draft is the selection surface, stored so what an operator reviews is exactly what postVendorPaymentRun records. Bills that are ready but cannot be grouped — no vendor on the order, a currency this rail cannot settle — are reported in skipped rather than dropped. Access: 'accountingPost' in a workspace where finance is enabled — the same permission the sweep needs, because a draft run lists every vendor balance in the workspace. Errors: refuses a workspace with nothing ready to pay, and a selection larger than one run sweeps (narrow it with vendorAccountIds).
postVendorPaymentRun
Records, in the Hive ledger, one payment per vendor group in a draft run as already paid outside Hive. Does not send, submit or move money. Each group settles that vendor's bills through the same bookkeeping path createVendorPayment takes, in order. A group that cannot be recorded — its bills changed after the run was built, its period closed, its payment account was retired — records the refusal on its own row and the remaining groups are still recorded. Re-posting a completed run returns it unchanged rather than recording it twice; a run still being posted is refused. Access: 'accountingPost' in a workspace where finance is enabled. Errors: throws when the run does not exist, is not a draft, or is already being posted. Everything one vendor's payment can refuse is reported on that group.
postPurchaseOrder
Posts an approved purchase order to the ledger as a vendor bill.
approveWorksheetForPm
Approves a billing worksheet at the project-manager review step.
approveWorksheetForBilling
Approves a billing worksheet at the billing review step.
rejectWorksheets
Rejects a selection of submitted or PM approved worksheets, one at a time, by running rejectWorksheet for each — so each one releases its lines' claims on their source rows, appends its approval-chain step and notifies exactly once. A worksheet that cannot be rejected is reported in results and leaves the rest of the selection untouched.
Access: Requires the finance feature and the worksheet review permission — the same permission rejectWorksheet enforces, asserted per worksheet. Ids are confined to workspaceId, so a worksheet in another workspace is reported as not found rather than by its status.
Errors: Throws when the user is not logged in, the workspace has finance disabled, the selection is empty, or it names more worksheets than one run allows. Everything a single rejection can refuse — a missing worksheet, a status that cannot be rejected, a missing rejection reason, a lacking permission — is reported per row in results rather than thrown.
generateCustomerInvoiceDraft
Creates a draft customer invoice from a billing-approved worksheet.
generateCustomerInvoiceDrafts
Converts a selection of billing-approved worksheets into draft customer invoices, one per worksheet, by running generateCustomerInvoiceDraft for each. A worksheet that cannot convert is reported in results and leaves the rest of the selection untouched.
Access: Requires the finance feature and the billingInvoiceGenerate permission — the same permission generateCustomerInvoiceDraft enforces, asserted per worksheet. Ids are confined to workspaceId, so a worksheet in another workspace is reported as not found rather than by its status.
Errors: Throws when the user is not logged in, the workspace has finance disabled, the selection is empty, or it names more worksheets than one run allows. Everything a single conversion can refuse — a missing worksheet, a worksheet not yet billing-approved, an already-invoiced status mismatch, no billable lines, a payment-term problem — is reported per row in results rather than thrown.
saveCustomerInvoiceLine
Adds or updates a line on a draft customer invoice.
updateCustomerInvoiceLayout
Updates the presentation settings of a saved invoice layout. Omitted sections, style and assignment rules are preserved. Invoices using this layout display its current settings. Access: Finance users with invoice generation permission in the specified workspace. Errors: Refuses a missing layout, a layout outside the workspace or invalid presentation settings.
createReceipt
Records in the Hive ledger a customer payment that was already received outside Hive. Does not collect or move money.
voidReceipt
Voids a posted receipt: reverses the journal that posted it and puts every invoice it applied to back to the balance it carried before. The reversal is numbered after the original journal with a -VOID suffix rather than drawn from the series. Refused on a receipt already voided, one that never posted, one whose journal is cleared on a bank reconciliation, and one recorded in a currency other than the workspace's.
createWorksheetBatch
Creates one billing worksheet for each selected project.
createAccountingExport
Creates an accounting export for the selected finance source types.
updateGLAccount
Updates a GL account. Requires the setupUpdate finance permission.
Classification and type are fixed once the account carries journal lines — the entries posted to it were shaped around what they mean. Renaming stays available, and archiving is handled by archiveGLAccount.
postWipBatch
Posts WIP to the ledger, either way round: pass batchId to post a batch already prepared as a draft — it keeps its own document number and claims its source lines — or pass input to prepare and post in one step. Exactly one of the two. Claiming the source lines is what stops a second batch billing the same work, so a line another batch already took makes the whole post refuse. Access: signed-in members of the batch's workspace with the accountingPost permission, in a workspace where finance is enabled. Errors: neither batchId nor input given, or both; WIP batch not found; batch is no longer prepared, which is also what a losing race sees; batch nets to zero; WIP settings incomplete — posting needs both a WIP asset and a revenue account; no approved, unbilled worksheet lines eligible; one or more source lines already posted to WIP or belonging to another project; posting date inside closed books; and a refusal to post at all when the deployment cannot run the write in a transaction, which keeps the journal, the line claim, and the batch together.
discardWipBatch
Discards a prepared (draft) WIP batch. Drafts hold no journal and claim no worksheet lines, so nothing is released or reversed; a posted batch is unposted, not discarded. The reason is sanitized, and one made only of whitespace or markup is stored as no reason at all. Access: signed-in members of the batch's workspace with the accountingPost permission, in a workspace where finance is enabled. Errors: WIP batch not found; batch is not prepared — a posted batch is unposted instead, and an already-discarded one cannot be discarded twice; and a concurrency refusal when the batch leaves the prepared state while this discard is running.
voidRetainer
Cancels a retainer agreement and returns the unused funded balance, reversing it out of the retainer liability into the bank the money arrived in. Refuses when nothing is left funded — a fully drawn retainer is closed, not voided. Access: signed-in members of the retainer's workspace with the accountingUnpost permission, in a workspace where finance is enabled. Errors: retainer not found; retainer already voided; nothing left funded to return; funded liability does not match the unapplied balance (reconcile first); funded through more than one cash account; no retainer liability account configured for a retainer that has no funding journal; posting date inside closed books; and a refusal to post at all when the deployment cannot run the write in a transaction, which keeps the cancellation and its reversal together.
lockAccountingPeriod
Locks an accounting period against further changes.
reverseJournal
Reverses a posted journal. Requires the accountingUnpost finance permission.
Only manual entries and their own reversals may be reversed here. A journal a document posted is reversed through that document — void the invoice, void the retainer, unapply the receipt — so the document and the ledger move together.
createPriorPeriodCorrection
Creates a correction for a posted journal from a prior period.
unpostJournal
Unposts a posted journal by reversing it into its own period. Requires the accountingUnpost finance permission, and carries the same ownership rule as reverseJournal: document postings are unposted through the document that made them.
startFinanceQuickBooksMigration
Starts a QuickBooks finance migration.
refreshFinanceReferenceData
Refreshes connected provider data while preserving Hive-owned accounting fields. Access: Finance setup editors. Errors: refuses unsupported providers, missing access, or an active sync.
proposeFinanceMigrationAccountMatches
Proposes account matches for a finance migration run.
resolveFinanceMigrationAccountMatches
Applies account-match decisions to a finance migration run.
rollbackFinanceMigrationRun
Rolls back a finance migration run.
previewFinanceTrialBalanceImport
Previews the supplied trial-balance rows for a finance migration. Writes: replaces the migration run's staged preview rows; nothing reaches the ledger.
applyFinanceTrialBalanceImport
Imports the trial balance for a finance migration run.
importFinanceOpenAr
Imports open accounts-receivable items for a finance migration run.
importFinanceOpenAp
Imports open accounts-payable items for a finance migration run.
createOpeningReconciliation
Creates the opening reconciliation for finance migration.
executeTrainingDataCleanup
Removes finance training data from the workspace.
resetWorkspaceFinanceData
Resets finance data in the workspace after confirmation.
seedWorkspaceFinanceDemoData
Seeds the workspace with finance demo data.
recaptureReconciliationLines
Capture onto an open reconciliation whatever its statement window now holds and it does not: posted book lines and unclaimed bank lines in the statement's own company, on exactly the rule the create used. Adds only — cleared, matched and locked lines are left untouched — so a statement created before its feed or its journals had landed can be corrected in place instead of being permanently empty. Access: workspace members with the financial feature and the accountingReconcile permission. Errors: the reconciliation does not exist; it is finalized rather than draft or reopened; its statement period is closed or locked.
toggleReconciliationLine
Marks a reconciliation line as cleared or uncleared.
matchReconciliationLines
Matches a bank statement line to a book line.
unmatchReconciliationLine
Removes the match from a reconciliation line.
resolveReconciliationException
Records a resolution for a reconciliation exception.
previewPosting
Previews the journal entries for a finance posting request.
syncStripeTaxCodeCatalog
Synchronizes the Stripe tax-code catalog for the workspace.
createFinanceExchangeRate
Stores an exchange rate for a currency pair on a day. One rate per pair per day per company: two rates for the same day would make 'the latest rate on or before this date' ambiguous, so the second is refused rather than stored beside the first. Access: 'setupUpdate' in a workspace where finance is enabled. Errors: a currency is missing or the two match; the rate is not a decimal greater than zero; a rate for this pair on this date already exists.
updateFinanceExchangeRate
Corrects a stored rate's value or the day it applies from. There is no delete and no archive: a rate is superseded by a later dated row, and a row entered against the wrong day is moved to the right one. Editing marks the rate manual, so a later provider refresh cannot revert a correction someone made on purpose. Access: 'setupUpdate' in a workspace where finance is enabled. Errors: the rate does not exist; the new rate is not a decimal greater than zero; the new date already holds a rate for this pair.
createFinancePaymentTerm
Adds a payment term to this workspace. Terms are master data: they name a due rule that dates the invoices billed against them. Company attribution is recorded from this first write for the GL companies provisioning will introduce, and is null until they exist. A term may also offer an early payment discount, earned in a window measured the way the term itself falls due and closing no later than it does. Access: signed-in members of the workspace with the setupUpdate permission, in a workspace where finance is enabled. Errors: the name is empty, too long, or already held by an active term in this workspace; the input names both a day count and a day of the month, or neither; a due field is outside its range; the discount names a percentage without a window or a window without a percentage; the discount percentage is not above 0 and at most 100; the discount window is measured in the unit the term does not fall due in; the discount window closes after the term falls due; or a discount window is outside its range.
updateFinancePaymentTerm
Edits a payment term, including terms imported from an accounting system — the importer owns the provider reference on the row, not its due rule. Invoices already dated from this term keep the due date they were given; the rule applies from the next invoice billed against it. Access: signed-in members of the workspace with the setupUpdate permission, in a workspace where finance is enabled. Errors: the term does not exist or is deleted; the new name is empty, too long, or already held by another active term; the input names both due fields; or a due field is outside its range.
deactivateFinancePaymentTerm
Retires a payment term from new billing. This is a status change, not a delete: the term stays readable so invoices that name it still resolve, and the same edit sheet reactivates it. Access: signed-in members of the workspace with the setupUpdate permission, in a workspace where finance is enabled. Errors: the term does not exist or is deleted.
createFinanceGlCompany
Provisions a company that keeps its own set of books. The first company a workspace adds becomes its default whatever the input says. Access: 'setupUpdate' in a workspace where finance is enabled. Errors: the company ID or name is blank; the company ID is already used in this workspace; the currency is not the workspace base currency; the workspace has no finance setup profile; another request moved the default while this one saved.
updateFinanceGlCompany
Edits a GL company, including retiring one by setting active to false. There is no archive: a company transactions reference is deactivated, never removed. Access: 'setupUpdate' in a workspace where finance is enabled. Errors: the company is not found; the company ID or name is blank; the company ID is already used in this workspace; the default company was asked to clear its own flag or to deactivate; a company outside the workspace base currency was asked to become the default; another request moved the default while this one saved.
createFinanceIntercompanyMapping
Opens intercompany posting from one GL company to another, through the due-from and due-to accounts the pair balances across. Direction matters: a mapping from A to B is what lets a journal written from A reach into B's books, and B to A is a separate row. Access: 'setupUpdate' in a workspace where finance is enabled. Errors: either company does not exist in this workspace or is inactive; the two are the same company; this ordered pair is already mapped; the due-from account is not an active other current asset or the due-to account is not an active other current liability.
updateFinanceIntercompanyMapping
Changes the accounts an intercompany pair posts through, or retires the pair. The pair itself cannot be repointed — retire this mapping and add the one that was meant. Access: 'setupUpdate' in a workspace where finance is enabled. Errors: the mapping is not found; an account named is not an active account of the type its leg requires — including when reactivating a mapping whose accounts were archived meanwhile.
createFinanceEliminationEntry
Drafts a consolidation adjustment. Nothing is checked beyond the shape of the lines here — the group, the accounts and the calendars are asked at post time, when the entry starts changing what a statement reports. Access: 'accountingPost' in a workspace where finance is enabled. Errors: the entry has no lines, or a line carries both a debit and a credit, neither, or a negative amount.
updateFinanceEliminationEntry
Replaces a draft entry's date, memo and lines together. Posted and reversed entries are immutable — reverse one instead. Access: 'accountingPost' in a workspace where finance is enabled. Errors: the entry is not found or is no longer a draft; the lines fail the same shape checks create applies.
deleteFinanceEliminationEntry
Deletes a draft entry. Posted and reversed entries are kept — reverse one instead. Access: 'accountingPost' in a workspace where finance is enabled. Errors: the entry is not found or is no longer a draft.
postFinanceEliminationEntry
Posts a consolidation adjustment, which is what makes consolidated statements report it.
Balance is asked of the entry as a whole and deliberately not per company: taking one company's due-to out against another's due-from unbalances both on purpose, and that is the entry. Every company it names must exist and hold an open period on the entry's date, and every account must be live. Access: 'accountingPost' in a workspace where finance is enabled. Errors: the entry is not found or is not a draft; it names fewer than two companies; its debits and credits do not agree; its lines are not all in the workspace base unit; a company or account it names is missing or inactive; a company's period is closed on that date.
reverseFinanceEliminationEntry
Takes a posted adjustment back out by posting its mirror on a date of its own, so a statement already run as of an earlier date keeps reporting what it reported. Access: 'accountingUnpost' in a workspace where finance is enabled. Errors: the entry is not found or is not posted; the reversal date is before the entry's own date; a company the entry names has a closed period on the reversal date.
setFinanceMasterDataActive
Activates or retires master-data records in bulk: services, items, tax codes, classes and payment terms. Each row is flipped through that entity's own update mutation, so a bulk change means exactly what the same change means in the edit sheet. This is not one of the legacy bulk* mutations and takes no status string — master data has no document lifecycle, only the active flag its Active/Closed status is derived from.
A row already in the requested state is reported as succeeded and left untouched, so a selection that mixes active and inactive rows records no change for the ones that had none.
Rows are independent: a row that cannot be flipped is reported in results with its reason and does not stop the rest.
Access: signed-in members of the workspace with the setupUpdate permission each entity's update mutation enforces, in a workspace where finance is enabled. Errors: the workspace has finance disabled, the user is not logged in, or records is empty.
reserveDocumentNumber
Reserves the next document number for the selected finance document type.
syncPlaidBankConnection
Pulls read-only account balances and transactions from the connected bank via Plaid (transactions product) into Hive. Cannot initiate payments or transfers.
setPlaidBankFeedScope
Sets how much of a Plaid connection's read-only transactions feed Hive stores, and returns the connection reading the new scope. Switching to PAUSED stops every sync of it; switching to BALANCES_AND_PENDING lets balances and pending rows through and leaves the posted feed to whichever connection owns it. A connection the provider has flagged keeps that status: the scope says what Hive stores, not whether the bank is reachable, and the next sync is what re-derives the second answer. Access: the finance setup permission in the connection's workspace, in a workspace where finance is enabled — the same gate every other bank-connection mutation uses. Errors: 'Plaid bank connection not found.' when no live connection has that id. Setting the scope a connection already runs under is not an error; it writes the same word again.
disconnectPlaidBankConnection
Revokes Hive's read-only Plaid access to a bank connection and removes it from the workspace. Does not affect the bank account itself.
createBankConnection
Creates a bank-connection record in Hive's database. Does not contact Plaid or any bank and cannot initiate payments.
applyBankRules
Applies active bank rules to eligible unmatched transactions.
matchBankTransaction
Matches a bank transaction to a corresponding finance record.
createBankTransactionPostingBatch
Creates a posting batch from selected bank transactions.
rejectBankTransactionPostingBatch
Decline the held bank-feed batch behind this draft journal, releasing its transactions.
generateFixedAssetSchedule
Generates the depreciation schedule for a fixed asset.
postFixedAssetDepreciation
Posts a fixed asset depreciation schedule row to the ledger.
createFinanceApprovalRule
Create an approval rule. Audited: rules gate money thresholds, so the insert and its audit event share one transaction. Access: 'setupUpdate' in a workspace where finance is enabled. Errors: refuses a rule that can hold nothing — no record types, no approver steps, or two steps claiming the same sequence — and refuses a blank or over-long name.
updateFinanceApprovalRule
Replace an approval rule. A full overwrite guarded by a modifiedAt compare-and-set, so a concurrent edit is refused rather than silently losing the other operator's change. Access: 'setupUpdate' in a workspace where finance is enabled. Errors: the create-side validation, plus a refusal when the rule changed while being edited. Documents already held by this rule keep the route they were given — their copy does not move.
updateTaxProviderSetting
Updates the workspace tax provider configuration.
setBankFeedOwner
Move one GL cash account's posted bank feed to this connection, from a named day.
Shadow rows this connection already stored for the account are settled by the same date: those dated on or after the cutover become the register's own, and those dated before it are removed as a second copy of transactions the register already holds. A QuickBooks import skips its own bank rows for the account from the cutover day.
Access: finance feature access and the setupUpdate permission, the gate every other bank
connection change takes.
Errors: refuses when the connection is not a Plaid connection on the full bank feed, when it has no live bank account mapped to the GL account, when that account's feed has already been moved, when the workspace's QuickBooks sync is still connected, when Plaid is syncing, when the date is in the future, or when the previous feed already has rows from that date onward. Also refuses when the two feeds disagree on any of the 30 days before the cutover, naming that day, both counts and both totals.
updateFinanceMinimumCash
Updates or clears the workspace minimum-cash floor used by cash forecasting. Access: signed-in members of the workspace with the setupUpdate permission, in a workspace where finance is enabled. Errors: the amount is negative or does not use the workspace base money unit.
postRevenueRecognitionLine
Recognizes one scheduled line: posts the deferred-revenue-to-revenue journal and stamps the line posted in the same transaction. When the schedule recognizes an advance billing, the document's own deferred schedule moves with it — the two share the line id. Access: signed-in members of the line's workspace with the accountingPost permission, in a workspace where finance is enabled. Errors: line or schedule not found; deferred revenue or revenue account not eligible; the posting date falls in a closed period; or the line changed while it was being posted.
createAccountingAllocationRule
Defines how a pool account is spread across receiving segments: the basis rows and their weights, and the two accounts its runs post between: the source pool it is spread from and the target account each receiving segment is charged in. Access: signed-in members of the workspace with the setupUpdate permission, in a workspace where finance is enabled. Errors: either account is missing or archived; or the rule would allocate nothing, charging the same account it relieves with no basis row naming a dimension.
updateAccountingAllocationRule
Replaces an allocation rule's definition. Runs already posted keep the lines they posted; only future runs use the new basis. Access: signed-in members of the rule's workspace with the setupUpdate permission, in a workspace where finance is enabled. Errors: rule not found; either account is missing or archived; or the rule would allocate nothing, charging the same account it relieves with no basis row naming a dimension.
createAccountingAllocationRun
Creates a draft run: the rule's basis split applied to a total, stored as lines that sum to it exactly. Nothing posts until postAccountingAllocationRun. Access: signed-in members of the workspace with the setupUpdate permission, in a workspace where finance is enabled. Errors: rule not found or inactive; the rule changed since the preview named by ruleModifiedAt; the total is not in the workspace base currency, scale and half-up rounding; the rule's basis total is not positive; or the total amount is not positive.
postAccountingAllocationRun
Posts a draft run: writes the balanced allocation journal and its posting batch, and stamps the run posted in the same transaction. Re-posting a posted run returns it unchanged. Access: signed-in members of the run's workspace with the accountingPost permission, in a workspace where finance is enabled. Errors: run or rule not found; an allocation account is missing or archived; the posting date falls in a closed period; or the run changed while it was being posted.
postAccountingAllocationRuns
Posts several draft runs as one month-end batch, through the same per-run path postAccountingAllocationRun uses. All or none: a period's allocations do not half-post, so a refusal on any run leaves every one of them a draft. Runs already posted are returned untouched rather than refused, so retrying a batch is safe. Access: signed-in members of the workspace with the accountingPost permission, in a workspace where finance is enabled. Errors: any named run is missing from this workspace; or any run fails the checks postAccountingAllocationRun applies — draft status, accounts, dimensions, period gate, posting-account snapshot.
reverseAccountingAllocationRun
Reverses a posted run: writes the reversing journal against the run's own posted entry, closes that entry, and stamps the run reversed — all in one transaction. This is the only way to undo a posted allocation; reverseJournal refuses the run's journal because it is owned by a document lifecycle, which is this one. Access: signed-in members of the run's workspace with the accountingUnpost permission, in a workspace where finance is enabled. Errors: run not found; the run is not posted; its journal is missing; the reason is empty once markup is stripped; the reversal date falls before the original posting date or in a closed period; or the run changed while it was being reversed.
createFinanceRevaluationRun
Creates a draft revaluation run: every open foreign-currency balance priced at the date's rate, stored with both rates and both home figures per document. Nothing posts until postFinanceRevaluationRun. Access: signed-in members of the workspace with the setupUpdate permission, in a workspace where finance is enabled. Errors: everything previewFinanceRevaluationRun refuses, plus no unrealized exchange gain/loss account configured, and a run already holding the date — named, with its status, so the caller knows whether it is a draft they can discard.
discardFinanceRevaluationRun
Discards a draft run, giving back the day it holds so the date can be revalued again. A draft holds no journal and claims nothing, so nothing is reversed or released. A posted run is refused: its adjustment is in the ledger and leaves it only through the auto-reversal its own journal owes. Access: signed-in members of the run's workspace with the setupUpdate permission — the grant that created the draft — in a workspace where finance is enabled. Errors: run not found or already discarded; the run is posted; or it left the draft state while the discard was running.
postFinanceRevaluationRun
Posts a draft run: one control-account line per document whose adjustment is non-zero and one line to the unrealized gain/loss account, written as a balanced journal that auto-reverses on the first day of the following month. Re-posting a posted run returns it unchanged. Access: signed-in members of the run's workspace with the accountingPost permission, in a workspace where finance is enabled. Errors: run not found or not a draft; the unrealized gain/loss or a control account is missing or no longer eligible; the posting date falls in a closed period; or the run changed while it was being posted.
createFinanceRecurringSchedule
Creates a recurring finance schedule.
updateFinanceRecurringSchedule
Updates a recurring finance schedule.
generateFinanceRecurringScheduleNow
Generates the occurrence this schedule already owes, now, instead of waiting for the nightly run — the same planner, the same generator and the same claim, taken early.
It cannot bill early: "now" advances the timing of the run, never of an occurrence, so a schedule whose next occurrence is still in the future is refused rather than pulled forward. Access: the permission that authors this schedule's document type by hand.
refreshFinanceTieOutHealth
Re-walk the subledgers and store the result, then return it.
The read above reuses the stored measurement while the ledger has not moved under it, so this is for what that cannot see: a bank reconciliation finalized elsewhere moves the bank rail without posting anything. It is a mutation rather than an argument on the query because it writes — the stamp every reader of this workspace sees afterwards is the one this call left behind.
retypeInvoiceAdjustment
Name what an edit was for, after the fact. The number is untouched — only the type and the note move — so this can never break the tie-out the receipt exists to satisfy.
Transfer is not accepted: a transfer is a mirrored pair of receipts sharing one group, made by moving money between lines rather than by renaming a single adjustment.
createVendorBill
Records a bill a vendor sent, with no purchase order behind it — rent, software, insurance, a subcontractor's invoice. Returns it as a draft: nothing reaches the ledger until postVendorBill, and every A/P read gates on the journal posting writes. The bill's totals are the sums of its lines; a caller never sends them. Access: 'purchasingCreate' in a workspace where finance is enabled. Errors: refuses a bill with no vendor, no number or no lines, a number this vendor already has a live bill under, and a currency other than the workspace's.
updateVendorBill
Edits a draft bill. Draft only — approval is what fixes numbers somebody else authorized, and a posted bill is corrected by voiding it and recording the right one. Access: 'purchasingCreate' in a workspace where finance is enabled.
approveVendorBill
Agrees the workspace owes this bill. Not the same authority as posting it: the approver/poster separation is the segregation-of-duties ruling, and there is deliberately no auto-approve-on-create preference. Access: 'purchasingApprove' in a workspace where finance is enabled.
postVendorBill
Books the payable: Dr each line's account, Cr A/P for the whole bill, in the bill's own company, on the bill's own issue date. The bill then joins the A/P subledger, A/P aging and the payment run, and its balance is what a payment relieves. Access: 'accountingPost' in a workspace where finance is enabled. Errors: refuses a bill that is not approved, an issue date in a closed period, and a document whose lines do not sum to its total. Passing idempotencyKey makes the call safe to retry.
voidVendorBill
Reverses a posted bill out of the books and closes it. A void, not an unpost: the original entry and its reversal both stand, which is what an audited ledger requires. Access: 'accountingUnpost' in a workspace where finance is enabled. Errors: refuses a bill that is not posted, an empty reason, a void into a closed period, and a bill any payment has been applied to — void the payment first.
postExpenseReport
Posts an approved expense report to the GL: Dr the workspace expense posting account, Cr accounts payable, for the report's total. Reserves the report's ER- number on the way, stamps journalId/postedAt/postedBy and moves it to 'posted' — which is what puts it in the AP subledger, on Open Payables as ready for payment, and off the month-end close blocker. Approval stays non-GL and is untouched: its project cost entries keep firing where they always did, and this adds the ledger event after them. Access: 'accountingPost' in a workspace where finance is enabled. Errors: refuses a report that is not approved, one in a currency other than the workspace's (imported reports can carry one, past the create-time seal), a closed period, and a non-positive total.
unpostExpenseReport
Takes a posted expense report back out of the books: reverses its journal through the shared reversal builder, into the period the expense was booked in, and returns the report to 'approved' with journalId/postedAt/postedBy cleared. The report keeps its number, so a re-post is the same document rather than a second one. Not a void: an expense report is a person's claim, so unposting says the books were wrong rather than that the claim was, and the approval-time project cost entries are left standing. Rejecting is how a claim is cancelled. Access: 'accountingUnpost' in a workspace where finance is enabled. Errors: refuses a report that is not posted, one any reimbursement has been paid against (void the payment first), and a reversal into a closed period.
createExpenseReimbursement
Records in the Hive ledger that an employee expense reimbursement was already paid outside Hive. Does not pay the employee or move money. It is the employee-payee door onto the same bookkeeping path vendor bill payments are recorded through. Writes a FinanceVendorPayment carrying employeeUserId instead of vendorAccountId, allocated to the report, posts Dr A/P (under the report's identity, so the AP subledger and aging follow it) / Cr the payment account, and advances the report's paidAmount. The employee is never made a vendor account: that would drag a person into vendor tax profiles and 1099 eligibility. Void it with voidVendorPayment, which reopens the report's balance. Access: 'accountingPost' in a workspace where finance is enabled. Errors: refuses a report that is not posted, an amount above what the report still owes, and a payment in a currency other than the workspace's. Passing idempotencyKey makes the call safe to retry — a repeat returns the payment already recorded.
skipFinanceMigrationRow
Leaves a failed migration row out of its import so the run can finish. The row keeps the result code and message explaining why it failed, and records who skipped it, when, and why; it stops being retried by the apply and is counted as skipped in the run's apply summary. Nothing brings it back: retrying a skipped row is refused and a requeue leaves it alone, so the row stays out for the life of the run. Access: signed-in members of the run's workspace with the setupUpdate permission, in a workspace where finance is enabled — the same gate retryFinanceMigrationRow asks for, because the two are the same decision about the same row. Errors: row not found in the named run; a row that is not failed (an applied, pending or already-skipped row has nothing to dispose of); an empty reason.
reapplyFinanceMigrationRowPostings
Rechecks the posting rails for applied QuickBooks rows of a finished import, repairing missing or outdated ledger entries against the current source revision. It does not re-apply source documents. Rows without a current source reference or live target are left unchanged and counted in unverifiedCount. Walks the run in row-id order: pass the previous call's lastRowId as afterRowId and continue while hasMore is true. Access: signed-in members of the run's workspace with the setupUpdate permission, in a workspace where finance is enabled — the gate retryFinanceMigrationRow and skipFinanceMigrationRow ask for, because all three are the same decision about the same rows. Errors: run not found; a run whose processing lease is still live.
resolveFinanceWorkamajigProjectMatches
Records the importer's decisions for projects a Workamajig historical import holds for review: link each to a Hive project already in a team's tree, or create it private to them. Once none is left undecided, the import continues to apply. Access: the member who started the import, with Finance setup edit access. Errors: a run not waiting on review; a row that is not a held project; a project the caller can't see.
beginStripeFinanceConnection
Starts Stripe's workspace authorization flow. Successful connections begin in read-only mode. Access: Finance setup editors. Errors: Stripe is not configured, or workspace access or setup-update permission is missing.
setFinanceSourceConnectionMode
Changes an operating source among disabled, read-only, and shadow modes. Access: Finance setup editors. Active mode requires activateFinanceSourceConnection. Errors: connection is missing, inaccessible, or active mode was requested.
activateFinanceSourceConnection
Activates authoritative posting from shadow mode after the operator repeats the displayed assertion exactly. Access: Finance setup editors who can post accounting entries. Errors: connection is missing, inaccessible, not in shadow mode, or the assertion does not match.
deactivateFinanceSourceConnection
Returns an active operating source to read-only mode and clears its activation receipt. Access: Finance setup editors. Errors: connection is missing or inaccessible.
configureStripeFinanceChargeMapping
Stores exact GL accounts for Stripe charge journal parity in one currency. Access: Finance setup editors. Errors: connection is missing or not Stripe, or accounts are inactive, duplicated, or use another currency.
configureSubscriptionPostingMapping
Stores, on a Chargebee connection, the GL accounts and the first month of its month entries. Access: Finance setup editors. Errors: connection is missing or not Chargebee, the month is not YYYY-MM, or an account is inactive or has the wrong classification.
postSubscriptionMonth
Posts the month entries of a Chargebee connection, in this order: billing, payments, revenue, Stripe activity. Each entry is the total from the first month through this month minus what is posted, so a repeat with no change posts nothing. A refusal stops the run; the entries before it stay posted. Access: Finance accounting posters. Errors: connection is missing or not Chargebee, the mapping is not configured, or an entry is refused (month, accounts, period, a feed, or stored documents).
createStripeFinanceDrafts
Approves selected Stripe charge rows and creates idempotent draft journals. Never posts them. Access: Finance accounting posters. Errors: connection, mapping, source row, period, or GL account is unavailable or invalid.
createFinanceRetainerAgreements
Creates one direct retainer draft, or materializes every distinct retainer term from an accepted proposal as an independently traceable draft. One proposal-level default remains one term even when it governs several lines. Repeating proposal materialization returns the existing agreements. Access: signed-in workspace members with the billing invoice generate permission and write access to the selected company. Errors: invalid or past execution terms, unsupported cadence or currency, missing client or project references, unaccepted proposal terms, or conflicting proposal-subject identity.
updateFinanceRetainerAgreement
Updates execution terms on a draft agreement. Accepted proposal economics remain immutable. Access: same billing invoice generate and company-write gates as creation. Errors: agreement not found, non-draft status, stale concurrent edit, invalid references or execution terms, unsupported currency, or a change to accepted proposal economics.
updateFinanceRetainerSubscriptionLink
Repairs or clears the CRM subscription link on any retainer status without changing billing terms or executor version. Omit subscriptionExternalId to retain the link; null clears it. Requires billing write, company-write, and CRM read access. Errors: agreement not found, denied access, stale agreement or link, or a subscription that does not belong to the retainer client.
activateFinanceRetainerAgreement
Activates a draft and creates its one recurring invoice executor, or resumes a paused one. Access: same billing invoice generate and company-write gates as creation. Errors: agreement not found, invalid lifecycle state or terms, stale concurrent update, or a missing resumable schedule.
pauseFinanceRetainerAgreement
Pauses an active retainer without consuming or moving its next invoice occurrence. Access: same billing invoice generate and company-write gates as creation. Errors: agreement not found, invalid lifecycle state, stale concurrent update, or no active agreement-owned schedule.
endFinanceRetainerAgreement
Ends an active or paused retainer and permanently closes its invoice executor. Access: same billing invoice generate and company-write gates as creation. Errors: agreement not found, invalid lifecycle state, or a stale concurrent update.
cancelFinanceRetainerAgreement
Cancels a draft, active, or paused retainer and permanently closes any invoice executor. Access: same billing invoice generate and company-write gates as creation. Errors: agreement not found, invalid lifecycle state, or a stale concurrent update.
runFinanceInvestigation
Investigate company-scoped customer payments and save research findings without changing the books. Consumes AI credits. Findings describe observed records, not a verified snapshot or authority to act. Access: accounting read and company/period access. Errors: access denied, revision conflict, research failure or unavailable AI credits. After an uncertain response, read the latest checkpoint before retrying.
startFinanceInvestigation
Start a durable research investigation without changing the books. Retrying the same request returns its original checkpoint. Access: accounting read and access to the accounting period's company. Errors: period not found, invalid input, or request key reused for a different question.
checkpointFinanceInvestigation
Save immutable research without changing accounting records. An identical retry returns the saved checkpoint. Re-read after a revision conflict. Access: accounting read and company/period access. Errors: investigation not found, invalid input or revision conflict.
ensureGoogleDriveFolder
Finds or creates a folder in the connected Google Drive account.
moveGoogleDriveFile
Moves a file in the connected Google Drive account.
createMailDraft
Create an email draft in the caller's connected Gmail or Outlook mailbox. Never sends: the draft stays in the mailbox's Drafts folder for the user to review and send themselves.
The HTML body is stored exactly as given (links are not rewritten or wrapped). Gmail drafts also carry a text/plain alternative derived from the HTML; Outlook derives its own on send.
For a reply draft pass inReplyTo (the replied-to message's internetMessageId) and, for Gmail, its threadId. Returns the created draft; its draftId is the id for updateMailDraft, updateMailDraftBody, getMailDraft and deleteMailDraft.
Access: Requires authenticated user with connected mail provider.
Errors:
- User is not logged in
- User does not have specified providerId connected
- Unsupported mail provider
- Recipient contains a line break
- Outlook reply target not found in the mailbox
updateMailDraft
Update an existing email draft's subject, body and/or recipients. Omitted fields keep their current value; a provided recipient list replaces the existing list. Attachments and reply headers are preserved, and attachFileIds adds files after the existing attachments. Never sends.
The HTML body is stored exactly as given (links are not rewritten or wrapped); on a reply draft the quoted thread is re-attached below it.
Access: Requires authenticated user with connected mail provider.
Errors:
- User is not logged in
- User does not have specified providerId connected
- Unsupported mail provider
- Recipient contains a line break
updateMailDraftBody
Update only the body content of a mail draft, preserving all other fields like attachments. hive-collab-server calls this when persisting collaborative mail draft edits. The HTML body is stored exactly as given (links are not rewritten); on a reply draft the quoted thread is re-attached below it. Never sends.
Access: Requires authenticated user with connected mail provider.
Errors:
- User is not logged in
- User does not have specified providerId connected
- Unsupported mail provider
createScheduledMailMessage
Create a scheduled mail message to be sent at a specified time. The message will be stored and processed by the scheduled mail processor.
Access: Requires authenticated user. User must have valid mail provider credentials.
Errors:
- User is not logged in
- Access denied - If the user does not own the specified email address.
saveEmailAttachmentToFileLibrary
Copies an attachment from the caller's connected Gmail or Outlook mailbox into Hive File Library, with optional folder placement and sharing. Requires an authenticated connected mailbox and write access to the target File Library folder. Missing or oversized attachments, provider failures, and inaccessible folders are rejected; maximum size is 15 MB.
upsertCrmPipeline
Creates or updates a workspace CRM pipeline and its ordered stages. Access: workspace admins. Errors: invalid names, probabilities, outcomes, or stage identifiers are rejected. A closed stage needs an outcome (won, lost, or noDecision) when it is created, edited, or restored.
archiveCrmPipeline
Archives a CRM pipeline while preserving referenced opportunities. Access: workspace admins.
archiveCrmPipelineStage
Archives a CRM stage while preserving referenced opportunities. Access: workspace admins.
updateOpportunity
Updates opportunity fields. Selecting a closed stage applies the same close bundle (forecast category, probability, closeDate) as closeOpportunity.
closeOpportunity
Closes an opportunity as won, lost, or dormant and applies its close-stage fields. Use this rather than updateOpportunity for explicit closure; both use the same close bundle. Confirm with the user before closing a Salesforce-synced opportunity whose externalId is set.
generatePipelineCoachSummary
Generates an AI coaching summary of the CRM pipeline (headline, summary, risks, opportunities, recommended actions), optionally scoped by owners and close-date window. Results are cached per scope for 24 hours; forceRefresh regenerates.
Access: workspace members with CRM access.
upsertOpportunityLines
Adds or edits priced lines (products, services, discounts) on an opportunity; lines with an existing _id are updated, others are created, and unlisted lines are left alone. Recomputes percentage discounts and fees and syncs the opportunity amount unless it was manually overridden or a primary proposal supplies it.
Access: workspace members with CRM access. Errors: opportunity not found, currency mismatch, invalid discount, fee, weeks or billing rule, catalog capacity exceeded.
deleteOpportunityLines
Permanently removes the given lines from an opportunity, then recomputes percentage discounts and syncs the opportunity amount unless it was manually overridden or a primary proposal supplies it.
Access: workspace members with CRM access. Errors: opportunity or any line not found.
resyncOpportunityAmount
Resets the opportunity amount to the total of its lines, clearing any manual amount override. Has no effect while a primary proposal supplies the amount.
Access: workspace members with CRM access. Errors: opportunity not found.
kickoffOpportunityProject
Starts delivery for a deal: creates (or reuses) a delivery project with sections per phase and actions per deliverable, each staffed with the roles it was priced with, and links the project to the opportunity and its account. With input.fillLinkedProject, a delivery project already linked to the deal gets these actions while it has no actions or child projects. Actions get their priced hours only when the caller may set time estimates. Fee and discount lines get no action. From an accepted proposal (proposalId, or else the deal's accepted proposal), builds from it and applies its budget. A deal with no accepted proposal builds from its saved estimate and leaves the budget to the won deal's baseline; without input.fillLinkedProject, a deal that already has a delivery project is returned unchanged.
Access: workspace members with CRM access to the opportunity and permission to create projects, plus access to the proposal it builds from. Errors: proposal not on this opportunity, not accepted, or has no lines; estimate has no deliverable lines; project creation failed.
draftOpportunityLines
Uses AI to draft priced lines for an opportunity from a free-text brief. Replaces all existing lines with the draft and overwrites the opportunity description with the generated summary.
Access: workspace members with CRM access. Errors: opportunity not found, empty brief.
linkOpportunityDeliveryProject
Links an existing project as the opportunity's delivery project. Replaces a link to a deleted project; does nothing when a live delivery project is already linked.
Access: CRM access to the opportunity and edit access to the project. Errors: opportunity or project not found.
createOpportunityBudgetBaseline
Cuts a won deal's estimate into its delivery project's first budget baseline and links the project to the deal's account (making it the client when the project has none). Winning a deal never cuts a baseline by itself; use this when getOpportunityCommercials reports budgetBaselineMissing. Returns the project; a repeat call once the deal's baseline stands is harmless.
Access: workspace members with CRM access who own the delivery project or are workspace admins. A won deal stands for the client's agreement, so like an accepted proposal the cut does not consult estimatesApprove or budget approval rules. Errors: opportunity not found; deal not won, has a proposal, or has no delivery project or lines; estimate and project currencies differ; project already has another budget.
createSequence
Creates a new outreach sequence in draft status with a name, owner, and optional description. Add its steps with createSequenceVersion, then activateSequenceVersion to make it live.
Access: workspace members with CRM access; owner must be assignable in the workspace.
updateSequence
Edits a sequence's name, description, owner, status, or final delay after the last step. Omitted fields are left unchanged; steps are edited through sequence versions.
Status changes act on the sequence's enrollments:
- archived: stops every running or paused enrollment for good and cancels emails queued but not yet sent. Setting the sequence active again does not resume them.
- paused or draft: holds every step until the sequence is active again, and cancels emails queued but not yet sent; they are queued again on reactivation.
- back to active from paused or draft: steps that fell due while held are spread out from now at their original spacing instead of all going at once. Setting the same status again finishes a stop or hold that did not complete.
Access: workspace members with CRM access; a new owner must be assignable. Errors: sequence not found.
createSequenceVersion
Creates a new draft version of a sequence with the given steps, numbered after the latest version. The live version is unaffected until this one is activated.
Access: workspace members with CRM access. Errors: sequence not found.
updateSequenceVersionSteps
Replaces the steps (and optionally the final delay) of a draft sequence version.
Access: workspace members with CRM access. Errors: version not found; version is not a draft.
activateSequenceVersion
Makes a sequence version the live one: archives the previously active version and sets the sequence to active on this version. Reactivates the sequence like updateSequence does: steps held while paused or draft are re-spaced, and enrollments of an archived sequence stay stopped.
Access: workspace members with CRM access. Errors: version not found; archived versions cannot be activated.
enrollPersonInSequence
Enrolls a CRM person in a sequence.
Access: workspace members with CRM access. Errors: sequence not found; the sequence is not active (draft, paused and archived sequences take no new enrollments, so do not retry until it is activated); the recipient is suppressed.
stopSequenceEnrollment
Stops a person's sequence enrollment so no further steps run, recording it as manually stopped; a linked campaign recipient is marked completed.
Access: workspace members with CRM access. Errors: enrollment not found.
previewSequenceEmail
Renders a sequence email for one contact the way a step run sends it: Hive's agent writes the AI blocks and builds the personalized attachment, with defaults for any part that fails. Nothing is sent.
Access: workspace members with CRM access. Errors: person not found.
createHttpConnection
Create a new HTTP connection in a workspace. Each connection becomes a tool named custom_http_{slug} that Buzz can use to make authenticated API requests.
IMPORTANT: "name" is a human display name (e.g. "Eric's Gmail Connection" or "GitHub API"). It must be unique within the workspace. Buzz derives the tool id from a slug of this name.
IMPORTANT: For snippet setup, create this only after researching MCP vs HTTP, recommending HTTP as the right path with setup/API key/auth docs links, and receiving user confirmation.
IMPORTANT: Unless you set nativeProvider, you MUST call discover_oauth_metadata before calling this. If discovery returns success, set authType to 'oauth' and use the discovered oauthAuthorizationUrl, oauthTokenUrl, and oauthScopes. Only use authType 'headers' when discover_oauth_metadata fails.
For Hive-managed apps, set nativeProvider instead of client id/secret/URLs. Sharing works the same as custom HTTP connections.
For authType "headers", either pass a "headers" object with auth credentials as key-value pairs (e.g. {"Authorization": "Bearer sk-xxx"}), or omit headers and call request_secure_input immediately after creation. Headers are encrypted at rest. Do not ask the user to choose header names or paste JSON unless the service docs require multiple secret fields.
Set sharingType to "everyone" for workspace-wide access, "custom" to share with specific users, or "me" (default) for personal use only.
After creating, inform the user that the new tool (custom_http_{slug}) will be available in their next conversation.
For an SFTP server that a Buzz snippet reads, skip OAuth discovery: set authType "sftp", origin sftp://host:port, sftpUsername and sftpHostKeyFingerprint, then call request_secure_input with the field "sftpPassword". An SFTP connection is never a custom_http_ tool; snippets read it with buzz.sftp.
updateHttpConnection
Update an existing HTTP connection by ID. Only the connection owner can change its credentials, origin, authentication or sharing; a Hive superadmin in the workspace can maintain its details (name, description, documentation link, enabled). If headers are provided, all existing headers are replaced with the new encrypted values.
insertLink
Creates a new link in the workspace's News panel.
Access: Requires user access to the workspace.
updateLink
Updates an existing link's title and url.
Access: Requires user access to the workspace.
removeLink
Soft deletes a link by setting deleted to true.
Access: Requires user access to the workspace.
createMcpServer
Create a new workspace-level MCP server connection. Use transportType 'streamable_http' for remote servers (requires url), or 'stdio' for local command-based servers (requires command). For snippet setup, create this only after researching MCP vs HTTP, recommending MCP as the right path with setup/MCP/auth docs links, and receiving user confirmation. IMPORTANT: Before calling this, you MUST call discover_oauth_metadata first. If discovery returns success, set authType to 'oauth' and use the discovered oauthAuthorizationUrl, oauthTokenUrl, and oauthScopes. Only use authType 'headers' when discover_oauth_metadata fails. After creating with OAuth, inform the user to click the Authorize button to complete the OAuth consent flow. For headers or stdio env credentials, use request_secure_input for the required secret fields; never ask the user to paste secrets in chat.
updateMeetingUserData
Update meeting user data using diff operations for array fields and direct values for scalars. Array fields (goals, agendaItems, nextSteps, materials, linkedActions, speakerLabels) accept add/remove/update diffs. Scalar fields (customTitle, notes, sharedNotes) accept direct values.
updateMeetingCustomFields
Replaces the named record's values for this workspace's meeting custom fields. Values for definitions this workspace does not own, or that are not meeting fields, are dropped; a field omitted from the array is cleared. Never creates a record: the record must belong to this meeting and be one the caller can read, and the write attributes to the caller.
updateMeetingOpportunity
Create or remove the canonical CRM linked_meeting association between a meeting and opportunity.
insertMessage
Sends a message or comment to a Hive chat, action, note, goal, project, opportunity, or notification.
Requires target-container access; participant-created direct messages require workspace access.
For an existing container, pass containerId and containerType. For a new direct message, omit
containerId and pass workspaceId, participants, and containerType: group. Participants must be
active workspace members, external members, or system admins, never stubs. Prefer bodyMarkdown
and omit body; body wins when both are supplied. To notify, put the 17-character user ID in
mentions and <@USER_ID> in bodyMarkdown; plain @name or @userId does not notify. To mention a
whole group chat, put GROUP:
editMessage
Edits a message's body, mentions, attachments, color, or action-comment visibility. Access: the message author or the human on whose behalf Buzz posted it, subject to container access. Send the full HTML body. Mentions and attachments replace existing values; copy their current values to retain them. Omit color and isPrivate to preserve them. Visibility changes apply only to action comments in client-mode projects and require internal users with writable workspace and project access. Errors: not logged in, not an authorized author, or insufficient access for the requested visibility change.
deleteMessage
Deletes a message by ID (soft-delete). Only the message creator can delete it — attempting to delete another user's message returns an access-denied error.
recoverMessage
Recovers a soft-deleted message by ID. Only the message creator can recover it — attempting to recover another user's message returns an access-denied error. Project comments also enforce the read-only project-member guard before recovery.
insertNewsCategory
Creates a new custom news category in the workspace.
On first write in a workspace, seeds the default categories and migrates any posts that were using legacy string category ids to the new random ids, then marks the workspace as newsCategoriesApplied.
Access: Requires user access to the workspace.
updateNewsCategory
Updates a news category's name and color.
Access: Requires user access to the workspace.
removeNewsCategory
Soft deletes a news category and un-sets it from any posts in the workspace.
Access: Requires user access to the workspace.
adminCreateProductVisual
Creates one agent-directed Highway Studio product visual from a creative brief or authoritative Release Item. Access: Authenticated Hive super admins. Errors: unauthenticated, unauthorized, invalid source or output controls, unavailable control plane.
insertPost
Creates a Hive news post with optional category, attachment, and predefined reactions. Requires access to the workspace.
removePost
Soft deletes a news post by setting deleted to true.
Access: Requires user to be the post creator or a workspace admin.
updatePost
Updates the body content of a news post.
Access: Requires user to be the post creator.
addPostReaction
Adds a reaction emoji to a post.
Access: Requires user access to the workspace.
removePostReaction
Removes a reaction emoji from a post.
Access: Requires user access to the workspace.
insertPostComment
Creates a new comment on a post.
Access: Requires user access to the workspace.
updatePostComment
Updates the body of a post comment.
Access: Requires user to be the comment creator.
removePostComment
Soft deletes a post comment.
Access: Requires user to be the comment creator or a workspace admin.
addPostCommentReaction
Adds a reaction emoji to a comment.
Access: Requires user access to the workspace.
removePostCommentReaction
Removes a reaction emoji from a comment.
Access: Requires user access to the workspace.
generateProposalDocument
Redrafts the proposal's Word document in the background; it takes a few minutes, and the draft opens in the proposal when it is ready while the previous one stays in its history. A first draft is written from the template; a redraft revises the document as it is now, following instructions (the changes asked for, and any answers the user gave). Access: caller must have CRM access to the proposal's workspace. Errors: when the proposal's inputs changed since they were last checked, call analyzeProposalReadiness with the same instructions instead.
analyzeProposalReadiness
Checks the proposal's requirements and evidence again, then redrafts it in the background following instructions. Use it when the deal record or the buyer's request changed. Access: caller must have CRM access to the proposal workspace. Errors: invalid inputs, unknown evidence references, technical analysis failure, or concurrent proposal changes.
saveProposalCommercialDraft
Saves this proposal's editable commercial lines and SOW billing rule without changing alternative offers. Lines, a refresh from the opportunity, or the SOW rule alone may be sent. Access: workspace CRM access. Errors: stale draft, accepted/sent offer, invalid lines or rule.
setOpportunityPrimaryProposal
Selects which proposal supplies the opportunity forecast. Access: workspace CRM access. Errors: proposal from a different deal or closed opportunity.
bulkInsertProjectTags
Adds resourcing project tags to projects. All items must belong to one workspace. Requires resourcing access in that workspace and access to every project. Existing tags are not deduplicated, and the customTagId/resourceTagId pairing is not validated. Returns the inserted ProjectTag records.
updateProject
Updates project settings and custom field values. Custom fields patch by field id; omitted fields stay unchanged. Access: project editors. Errors: unauthenticated, inaccessible or read-only project, invalid parent or custom field, or conflicting custom field inputs.
updateProjectParent
Moves a project beneath another project, or promotes it to the top level when parentProjectId is omitted, null, or empty. Access: project editors with Location permission. Errors: inaccessible project, cross-workspace parent, or cycle.
updateAssignedPlaceholders
Maps a resource placeholder (e.g. "Event manager") to a person on one project. With updateActions true, also assigns that person to the project's actions that use the placeholder (actions with their own mapping for it are skipped); otherwise only the project mapping changes. Requires placeholder-assign permission on the project.
addProjectOwner
Adds a user to a project's owner list without removing existing owners. To replace owners, add the new owner before removing the previous owner so the project never has zero owners.
removeProjectOwner
Removes a user from a project's owner list. Fails when the user is the project's only remaining owner; when replacing owners, add the new owner first.
adoptProjectForCrmEstimate
updateMembersPermissions
Adds, removes, or changes project access for specified members or teams. Applies the supplied permission, sharing type, and automation flag to every target; use permission REMOVE to remove access.
updateMembersPermissionsV2Batch
Batch update members permissions for multiple projects. Processes each project sequentially and continues even if individual updates fail (errors are logged).
Access: Requires access to each project
Returns: Array of successfully updated projects
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
deleteProject
Soft-delete a project and its related data.
Access: Requires project delete permission
Errors: Throws error if user doesn't have access to delete the project
insertProjectStatusUpdate
Append a project-level status update (Project Navigator status column). Requires project access. Use getStatusesForWorkspace to list valid statusId values.
Access: Requires project access
removeProjectStatusUpdate
Remove a project-level status update by statusUpdateId.
Access: Requires project access
bulkUpdateProjectStatuses
Bulk update project-level statuses for many projects in one call. Each row requires projectId. Resolve statusId or statusName against workspace Statuses. Returns per-row updated/skipped/failed outcomes.
Access: Requires workspace access; each row enforces project access, and rows for read-only members fail ("Read-only project access").
updateProjectTreeHiddenApp
Shows or hides one project app for a project and all of its descendant projects, leaving the other entries of each project's hiddenApps untouched. shouldHide false enables the app. Returns updated/skipped/failed counts; projects already in the requested state are skipped.
Access: Requires access to the root project and the workspace project edit permission; each project in the tree enforces project access and fails for read-only members.
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
updateProjectsCustomFieldsWithResult
Updates existing project custom fields on editable projects and reports readable read-only skips. Access: Workspace access and project custom-field update permission; field-level admin/owner rules apply. Errors: Workspace permission denial, invalid field values, or more than 5000 projects / 100 fields. Missing and unreadable projects are omitted. Archived editable projects can be updated.
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 action custom fields in specified projects. removeFromActions also removes their stored values from actions.
updateProjectOtherCosts
Adds, updates, or removes one project other-cost entry and recalculates derived totals. UPDATE clears description or categoryId when omitted, but preserves omitted date, type, and recurrence values. Requires workspace-admin or project-owner access. ADD and UPDATE require name and amount; UPDATE and REMOVE require costId. Duplicate IDs and invalid categories are rejected; negative amounts are allowed as credits.
createProject
Creates a new project in a workspace with comprehensive configuration options.
This is the primary mutation for project creation, supporting both basic project setup and advanced features like copying from existing projects, custom fields, etc.
Access: Requires user access to the workspace
Returns: The newly created Project object with all computed fields
Errors:
- Throws error if user doesn't have access to the workspace
- Throws error if copyFrom project doesn't exist or user lacks access
- Throws error if endDate is before startDate
- Throws error if members don't have workspace access
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
applyProjectTemplate
Apply a project template to an existing project.
This mutation copies settings, structure, and configuration from a template project to a target project based on the importWith flags.
Access: Requires user access to both template and target projects
Returns: The updated target project
convertActionToProject
Creates a project from an action and copies its subactions into the new project. The name defaults to the action title and membership defaults to the caller. Can apply a template, add members or teams, configure sharing, nest the project, and optionally delete the original action. Requires action and workspace access.
insertRecurringAction
Adds a recurrence schedule to an existing Hive action; create the action first. Supports daily, weekly, monthly, and annual patterns ending never, after a count, or on a date. Requires access to the action; missing or inaccessible actions are rejected.
unsetRecurringActions
Make actions non-recurring by removing their recurring linkage. Stops future recurring instances from being generated while preserving the action.
Parameters:
- actionIds: Array of action IDs to make non-recurring
- workspaceId: The ID of the workspace
Access: Requires user access to the actions.
Errors: Throws error if user lacks edit permission on the actions.
createReminder
Creates a one-time or recurring Hive reminder for specified workspace members and records its originating Hive object. Encode a one-time reminder with endingType after and endingAfter 1; recurring reminders use endingType never, after, or date with startDate.
deleteReminder
Soft-delete a reminder so it no longer fires (sets deleted: true). Pass reminderId from getReminders or getReminder.
For vague requests ("cancel that reminder", "kill the daily one"): call getReminders first. If several reminders could match, list the candidates in chat and ask the user which reminderId to delete before calling this mutation. Confirm success after deletion.
createResourceAssignment
Creates a resource assignment for a user or placeholder. Book client work on the client's project: look it up first (getProjects), because it usually exists. Only when the client has no project, propose createProject for the client, then book with its projectId. If the booking fails because the resource is not on the project, add them and book again; never drop projectId to get round it. Add a user with updateProjectMembersPermissions. Add a placeholder with updateProject resourcePlaceholderIds, sending the project's existing IDs plus the new one, because the list is replaced. Defaults are assignmentType regular, allocationType fixedHours, and fixedDisplayType hours. When overriding allocation or display, supply allocationType and fixedDisplayType together as a compatible pair:
- hoursPerDay + hours: set hoursPerDay.
- fixedHours + hours: set fixedHours to total allocated hours.
- fixedHours + days: set fixedHours to requested days times the workspace workday hours.
- fixedHours + percentages: set allocationValue to the percentage; allocated hours are derived across the assignment's working dates. allocationValue is only read in percentages mode; other modes ignore it and recalculate it.
updateResourceAssignment
Updates an existing resource assignment by ID. Resolve the exact ID with getResourceAssignments first; do not update when no assignment matches. When omitted, allocationType and fixedDisplayType keep the existing assignment's values. To change mode or set hoursPerDay, fixedHours, or allocationValue, send allocationType and fixedDisplayType together as a compatible pair (see createResourceAssignment); allocationValue is only read in percentages mode.
deleteResourceAssignment
Delete a resource assignment by its id within a workspace.
Soft-deletes the assignment (sets deleted: true) and clears its timesheets when the assignment was confirmed. Estimate Planner-owned assignments cannot be deleted. Pass the exact assignment id from a prior getResourceAssignments read; a missing or already-deleted id returns a not-found error. For stale-assignment cleanup, list candidates with getResourceAssignments and delete only after the user confirms. Returns true when an assignment was deleted.
syncTimeOffCalendarEvent
Sync a time-off resource assignment to the employee's connected calendar as an OOO block. Uses the organizer's hiveMail/hiveCalendar OAuth credentials. Calendar sync is optional; returns success: false with reason when the calendar is not connected.
createResourcePlaceholder
Creates a virtual team member for planning assignments before a person is designated. Workspace admins can also set bill and cost rates; other users can set the name and role.
updateResourcePlaceholder
Updates a resource placeholder's name, role, or financial rates without changing its identity or assignments. Passing null for roleTagId removes the role association. Only workspace admins can change bill and cost rates.
updateResourcePlaceholderTeams
Attributes a resource placeholder to the given teams for dashboard reporting, replacing any teams it was attributed to before. Pass an empty list to clear the attribution. Team membership is untouched. Requires resourcing access, not team edit permission.
Returns: the teams the placeholder is attributed to after the update
salesforceOperation
Runs Salesforce QUERY, SEARCH, INSERT, UPDATE, DELETE, UPSERT, MERGE, DESCRIBE, or CONVERT_LEAD. Uses an active workspace connection when workspaceId is supplied; otherwise uses the caller's connected Salesforce account. Requires a connection and valid operation-specific fields; parameter and Salesforce API failures are returned as errors.
sendSlackMessage
Post a freeform text message to a Slack channel or DM. Use getSlackChannels or getSlackDms to resolve channel IDs first. For sharing a Hive action card, use postSlackMessage instead. Access: Requires Slack connected in Apps.
postSlackMessage
Share a Hive action card to Slack (rich attachment). For plain text, use sendSlackMessage. Access: Requires Slack connected in Apps and edit access on the action.
addDashboardTab
Attach an existing dashboard as a project tab. Links the original dashboard and preserves its contents and sharing permissions. Access: Requires write access to the target project and read access to the dashboard. Errors: Throws when either resource is inaccessible or belongs to another workspace.
createTeam
Creates a team in the workspace and returns the created team. Requires non-external member access to the workspace. Fails when a team with the same name (case-insensitive, trimmed) already exists in the workspace.
updateTeamResourcePlaceholders
Replaces the resource placeholders attributed to a team for dashboard reporting. Team membership is untouched. Requires resourcing access, not team edit permission.
Errors: unknown team, no workspace or resourcing access, or placeholders that are deleted or outside the team's workspace.
updateTeamMembership
Adds or removes one member from multiple teams in one ordered operation while preserving all other current team members. Access: users allowed to edit the team. Errors: unknown teams, invalid workspace membership type, or insufficient team permissions.
insertTimeCategory
Creates a time category (billable by default) for classifying time entries. With projectId, it is also added to that project's category list when the project restricts categories.
Access: workspace members (external users excluded); admins only when the workspace restricts time category management.
updateTimeCategory
Renames a time category and optionally changes whether it is billable or time off.
Access: workspace members (external users excluded); admins only when the workspace restricts time category management. Errors: category not found or deleted.
deleteTimeCategory
Deletes a time category and unassigns it from projects and actions. Existing timesheets and time entries are preserved, including unsubmitted time. Their category reference is retained to distinguish missing categories without merging time or changing historical attribution.
Access: workspace members (external users excluded); admins only when the workspace restricts time category management. Errors: category not found or already deleted.
updateTimeEntry
Changes the logged time (in seconds) on an existing time entry, identified by its timesheet and date. snapshot, the per-item time breakdown, is accepted only for submitted or approved timesheets. Edits to approved time are pushed to Harvest when the workspace syncs timesheets. Use createTimeEntries to add new time.
Access: the timesheet's owner, or a workspace admin for someone else's timesheet. Errors: timesheet or time entry not found; manual project time disabled; snapshot does not match loggedTime.
createTimeEntries
Creates or updates workspace members' unsubmitted time entries. Workspace admins may target multiple members in one batch, including former (removed) members for historical imports; other callers may target only themselves. API keys act as their owning user and inherit that user's permissions, so admin-owned keys have the same cross-user access. Entries are grouped into weekly timesheets and upserted by user, container, category, and date. Submitted, approved, locked, unauthorized-user, and never-member writes are rejected. Use submitMyTimesheetsForApproval and updateTimesheetsStatus for status transitions.
updateTimeEntryComment
Adds or edits the comment on a time entry, or clears it with operation REMOVE.
Access: workspace members (external users excluded) who own or created the entry. Errors: time entry not found; caller is not its owner or creator.
createTimer
Create a new timer, optionally associated with an action
Access: Requires user to be logged in and have access to the workspace. If actionId is provided, the action must belong to the same workspace.
updateTimerStatus
Update timer status (start, pause, or complete)
- start: Sets status to running and adds a new session entry
- pause: Sets status to paused and closes current session entry
- complete: Sets status to completed and closes current session entry
Access: Requires user to be the owner of the timer
updateTimer
Update a timer's action association
Access: Requires user to be the owner of the timer. If actionId is provided, requires access to the new action's workspace.
deleteTimer
Delete a timer (soft delete)
Access: Requires user to be the owner of the timer
submitMyTimesheetsForApproval
Submits the authenticated user's existing unsubmitted timesheets by ID in an accessible workspace.
deleteTimesheet
Used for deleting timesheets in "timesheet" tab in "Timesheets" app.
Access: It requires user access.
Deleting a timesheet that is already deleted (or never existed) is an idempotent no-op that returns the current document (or null).
Errors: Returns specific expected errors if: 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
updateSubmittedTimesheets
Moves submitted project/category rows or frozen action rows to another project or time category. Can also remove selected frozen action rows. Live action tracking stays unchanged. Access: Requires workspace admin access. Errors: Fails for missing rows, mixed row types, leave rows, invalid targets, conflicting destination rows, or incompatible approval states.
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
updateUserFilterV2
Updates a saved Hive view filter. Client must merge existing userFilter.pivotTableColumns by columnId before calling — the mutation replaces pivotTableColumns with the payload array; partial arrays drop other columns. Call with layout dashboardWidget and actionViewId set to the widget's actionViewId; pass merged columns on filter.pivotTableColumns. Each column must include columnId and type. Omit conditionalFormatting. Formula values omit a leading equals sign; use DAYS(end, start) for date differences.
insertUserTag
Assigns one resourcing role or custom tag to a user or placeholder. Placeholder roles are set through updateResourcePlaceholder; bulk custom-tag changes use updateUserTags. Set exactly one of userId or placeholderId; the server derives customTagId for custom tags. Requires resourcing access and the matching tag or role permission; missing, mismatched, duplicate, or invalid resources are rejected.
updateUserTags
Adds or removes one custom resource tag for specified workspace users. Returns per-user updated, skipped, failed, and unresolved outcomes without aborting remaining users. Pass explicit user IDs after resolving any team membership; role tags use insertUserTag instead. Requires resourcing and tag-update access; missing or non-custom tags reject the whole batch.
updateUserProfile
Updates a workspace member's profile, managers, work dates, utilization target, or resourcing rates. Always pass the target userId. Editing another member requires workspace-admin access; managers, rates, the utilization target and work dates each also need their workspace permission, on the caller's own profile too. Use billRateFloat and costRateFloat rather than deprecated integer rate fields.
saveUserMemory
Save an explicit long-term Buzz memory for the current user.
Access: Requires authenticated user. Use only when the user explicitly asks Hive/Buzz to remember or save a durable personal preference, stable identity fact, or recurring instruction. Do not use for temporary task context, thread/project notes, full payment card numbers, CVV codes, passwords, tokens, or other secrets.
Errors: Throws if user is not logged in or memory is empty.
addProofVersion
Adds an uploaded Hive file as the next proof version of an action, creating the proof when the action has none. Same result as the card's "Add new file version" with "Upload only": no approval request is sent, and an AI review starts only when runAiReview is true. Access: users allowed to add proof versions to the action, with proofing enabled for the workspace, project and card, or continuing an existing review. Legacy external approvers of the proof cannot add versions. Errors: throws when the file is missing, still uploading, in another workspace, not uploaded by the caller or already a proof version; when the action's proof is a folder; when the project is archived; or when proofing is unavailable on the action.
applyActionTemplate
Applies an action template and returns section-placement details, including whether the default section was skipped.
updateWorkspaceSettings
Update workspace settings. Admin only.
When settings.notificationPolicy is set: the workspace policy is saved first, then locked fields are propagated to member UserSettings. If propagation fails, the mutation errors with NOTIFICATION_POLICY_PROPAGATION_FAILED while the workspace policy remains saved — retry the save (do not assume a full rollback).
updateWorkspaceFeatures
Turns workspace apps (features) on or off, e.g. { appWorkflows: true } enables the Workflows app. Caller must be a workspace admin; add-on and plan checks still apply server-side. Read getWorkspace.features afterwards to verify the change.
applyDemoUsersToWorkspace
Adds the demo bot members (Barb, Landon and Jessica) to a workspace and posts their welcome messages and sample actions to the caller. Access: workspace members who can start direct messages.
setCustomStatusColor
Sets, removes, or renames a custom workspace status color. Call after addStatusToProjectView when a new status needs a color.
MoveToNextStage
MyTimeEntry