Create, update or delete a task

distru-mutate-taskWrite

Creates, updates or deletes one task: a to-do with a due date, optionally assigned to a user and linked to one record.

Inputs

Every tool also takes the common inputs.

FieldTypeRequiredDescription
actionenum
CREATEUPDATEDELETE
Yes
idstringNoRequired for UPDATE and DELETE. Resolve via distru-search-tasks.
namestringNoRequired for CREATE.
descriptionstring or nullNoSend null to clear it.
statusenum
ACTIVECOMPLETED
NoACTIVE when omitted on CREATE. COMPLETED marks the task done.
dueDatestringNoRequired for CREATE. Cannot be cleared. ISO 8601 with a UTC offset, e.g. "2026-09-01T00:00:00-07:00"; the company timezone is on distru-get-me.
ownerIdstring or nullNoThe assignee. Resolve via distru-search-users, or distru-get-me for the user you're acting for. Omitted on CREATE leaves the task unassigned, so ask the user whether to assign it to them, to someone else or to no one. Send null to clear it.
locationIdstring or nullNoThe place to visit: one of a company's locations. Resolve via distru-get-company (includeLocations). Locations of a company that is itself a Distru account are refused. Send null to clear it.
colorenum or null
18 values
REDLIGHT_REDORANGELIGHT_ORANGEGOLDYELLOWGREENLIGHT_GREENBLUELIGHT_BLUECYANLIGHT_CYANINDIGOLIGHT_INDIGOPURPLELIGHT_PURPLEGRAYLIGHT_GRAY
NoCalendar color. Null, or omitted when creating, gives the company's default task color. Set only when the user asks for one.
assemblyIdstringNoResolve via distru-search-assemblies.
batchIdstringNoResolve via distru-search-batches.
companyIdstringNoResolve via distru-search-companies.
contactIdstringNoResolve via distru-search-contacts.
invoiceIdstringNoResolve via distru-search-invoices.
productIdstringNoResolve via distru-search-products.
purchaseOrderIdstringNoResolve via distru-search-purchase-orders.
returnIdstringNoResolve via distru-search-returns.
salesOrderIdstringNoResolve via distru-search-sales-orders.
customFieldsobject[]NoOnly the fields listed change. Required custom fields must be set, on update too, while still blank.
customFields[].customFieldIdstringYesResolve via distru-search-custom-fields (entityType TASK).
customFields[].valuestring or string[]YesTEXT: the text. DROPDOWN: the option name. CHECKBOX: an array of option names. DATE: YYYY-MM-DD, company timezone. "" or [] clears the field.

Output

This tool returns one of 2 shapes, depending on its inputs.

Presence on a nested field assumes its parent exists.

Result with task

FieldTypePresenceDescription
taskobjectAlways
task.idstringAlways
task.namestringAlways
task.descriptionstringCan be null
task.statusenum
ACTIVECOMPLETED
Always
task.dueDatestringAlways
task.colorenum
18 values
REDLIGHT_REDORANGELIGHT_ORANGEGOLDYELLOWGREENLIGHT_GREENBLUELIGHT_BLUECYANLIGHT_CYANINDIGOLIGHT_INDIGOPURPLELIGHT_PURPLEGRAYLIGHT_GRAY
Can be nullCalendar color. A record saved without one shows the company's default.
task.insertedAtstringAlways
task.updatedAtstringAlways
task.relatedTypeenum
ASSEMBLYBATCHCOMPANYCONTACTINVOICEORDER_SHIPMENTPRODUCTPURCHASE_ORDERREQUESTRETURNSALES_ORDERSTOCK_TRANSFER
Can be null
task.companyobjectNull or absent
task.company.idstringAlways
task.company.namestringNull or absent
task.salesOrderobjectCan be null
task.salesOrder.idstringAlways
task.salesOrder.orderNumberstringAlways
task.purchaseOrderobjectCan be null
task.purchaseOrder.idstringAlways
task.purchaseOrder.purchaseNumberstringAlways
task.invoiceobjectCan be null
task.invoice.idstringAlways
task.invoice.invoiceNumberstringAlways
task.productobjectCan be null
task.product.idstringAlways
task.product.namestringAlways
task.product.skustringAlways
task.batchobjectCan be null
task.batch.idstringAlways
task.batch.namestringAlways
task.contactobjectCan be null
task.contact.idstringAlways
task.contact.profileobjectAlways
task.contact.profile.fullNamestringAlways
task.assemblyobjectCan be null
task.assembly.idstringAlways
task.assembly.numberstringAlways
task.returnobjectCan be null
task.return.idstringAlways
task.return.returnNumberstringAlways
task.ownerobjectCan be null
task.owner.idstringAlways
task.owner.profileobjectAlways
task.owner.profile.fullNamestringAlways
task.creatorobjectCan be null
task.creator.idstringAlways
task.creator.profileobjectAlways
task.creator.profile.fullNamestringAlways
task.locationobjectCan be null
task.location.idstringAlways
task.location.namestringAlways
task.customFieldsobject[]Always
task.customFields[].customFieldobjectAlways
task.customFields[].customField.idstringAlways
task.customFields[].customField.namestringAlways
task.customFields[].customField.fieldTypeenum
CHECKBOXDATEDROPDOWNTEXT
Always
task.customFields[].valuestringCan be null

Result with id

FieldTypePresence
idstringAlways
What the AI reads

Creates, updates or deletes one task: a to-do with a due date, optionally assigned to a user and linked to one record. Use it to log work, assign follow-ups, reschedule, or mark a task done (UPDATE status COMPLETED); find tasks with distru-search-tasks. When the user hasn't said who the task is for, ask before CREATE whether to assign it to them, to someone else or to no one; don't assume. The assignee gets an in-app notification on CREATE and on every UPDATE, and a reminder email shortly before the due date while the task is ACTIVE. The linked record can be set on CREATE or on a task without one, then never changed or removed; to move a task to another record, tell the user and ask before creating a replacement or deleting the original. DELETE removes the task for good. CREATE and UPDATE return the task as distru-search-tasks does; DELETE returns its id. Sparse update: on UPDATE only the fields passed change and the rest stay as they are; a field sent as null is cleared, and a null color goes back to the company's default.