Create, update or delete a task
distru-mutate-taskWriteCreates, 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.
| Field | Type | Required | Description |
|---|---|---|---|
| action | enumCREATEUPDATEDELETE | Yes | |
| id | string | No | Required for UPDATE and DELETE. Resolve via distru-search-tasks. |
| name | string | No | Required for CREATE. |
| description | string or null | No | Send null to clear it. |
| status | enumACTIVECOMPLETED | No | ACTIVE when omitted on CREATE. COMPLETED marks the task done. |
| dueDate | string | No | Required 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. |
| ownerId | string or null | No | The 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. |
| locationId | string or null | No | The 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. |
| color | enum or null18 valuesREDLIGHT_REDORANGELIGHT_ORANGEGOLDYELLOWGREENLIGHT_GREENBLUELIGHT_BLUECYANLIGHT_CYANINDIGOLIGHT_INDIGOPURPLELIGHT_PURPLEGRAYLIGHT_GRAY | No | Calendar color. Null, or omitted when creating, gives the company's default task color. Set only when the user asks for one. |
| assemblyId | string | No | Resolve via distru-search-assemblies. |
| batchId | string | No | Resolve via distru-search-batches. |
| companyId | string | No | Resolve via distru-search-companies. |
| contactId | string | No | Resolve via distru-search-contacts. |
| invoiceId | string | No | Resolve via distru-search-invoices. |
| productId | string | No | Resolve via distru-search-products. |
| purchaseOrderId | string | No | Resolve via distru-search-purchase-orders. |
| returnId | string | No | Resolve via distru-search-returns. |
| salesOrderId | string | No | Resolve via distru-search-sales-orders. |
| customFields | object[] | No | Only the fields listed change. Required custom fields must be set, on update too, while still blank. |
| customFields[]. | string | Yes | Resolve via distru-search-custom-fields (entityType TASK). |
| customFields[]. | string or string[] | Yes | TEXT: 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
| Field | Type | Presence | Description |
|---|---|---|---|
| task | object | Always | |
| task. | string | Always | |
| task. | string | Always | |
| task. | string | Can be null | |
| task. | enumACTIVECOMPLETED | Always | |
| task. | string | Always | |
| task. | enum18 valuesREDLIGHT_REDORANGELIGHT_ORANGEGOLDYELLOWGREENLIGHT_GREENBLUELIGHT_BLUECYANLIGHT_CYANINDIGOLIGHT_INDIGOPURPLELIGHT_PURPLEGRAYLIGHT_GRAY | Can be null | Calendar color. A record saved without one shows the company's default. |
| task. | string | Always | |
| task. | string | Always | |
| task. | enumASSEMBLYBATCHCOMPANYCONTACTINVOICEORDER_SHIPMENTPRODUCTPURCHASE_ORDERREQUESTRETURNSALES_ORDERSTOCK_TRANSFER | Can be null | |
| task. | object | Null or absent | |
| task. | string | Always | |
| task. | string | Null or absent | |
| task. | object | Can be null | |
| task. | string | Always | |
| task. | string | Always | |
| task. | object | Can be null | |
| task. | string | Always | |
| task. | string | Always | |
| task. | object | Can be null | |
| task. | string | Always | |
| task. | string | Always | |
| task. | object | Can be null | |
| task. | string | Always | |
| task. | string | Always | |
| task. | string | Always | |
| task. | object | Can be null | |
| task. | string | Always | |
| task. | string | Always | |
| task. | object | Can be null | |
| task. | string | Always | |
| task. | object | Always | |
| task. | string | Always | |
| task. | object | Can be null | |
| task. | string | Always | |
| task. | string | Always | |
| task. | object | Can be null | |
| task. | string | Always | |
| task. | string | Always | |
| task. | object | Can be null | |
| task. | string | Always | |
| task. | object | Always | |
| task. | string | Always | |
| task. | object | Can be null | |
| task. | string | Always | |
| task. | object | Always | |
| task. | string | Always | |
| task. | object | Can be null | |
| task. | string | Always | |
| task. | string | Always | |
| task. | object[] | Always | |
| task. | object | Always | |
| task. | string | Always | |
| task. | string | Always | |
| task. | enumCHECKBOXDATEDROPDOWNTEXT | Always | |
| task. | string | Can be null |
Result with id
| Field | Type | Presence |
|---|---|---|
| id | string | Always |
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.