Tasks

Update a task

A partial write: send only the fields that change. To change a drench's head or products, prefer updateTreatmentRecord (treatment.id, not the task id). drench.products here also replaces the set. created_as is ignored on update. Back-dating uses completed_at with an Australian offset; see createTask.

Attaching a PurpleGrain AI record. To place a record with no asset (filter[unassigned]=true on listTasks), send the asset relationship (a mob or paddock you can edit). The task's farm is set from the asset. This works before and after the formatter has run, and on a record with no typed child. A treatment or husbandry record takes a mob; spray, fertiliser, sowing and field work a paddock. Editing a record never queues it for the formatter again.

PurpleGrain AI records are first-party. An MCP client cannot turn a task into one: a request from one that sets operation_type: ai on a task that is not already an AI record is refused with 403 and nothing is written. Sending an AI record's own type back while attaching its asset still passes.

Broadcasting is paused for agents. A request from an API or MCP client whose body names broadcast or share_scope — true or false — is refused with 403 and nothing is written; leave both out. First-party web and mobile requests are unaffected.

Photos. A file on disk: call createImageUpload, run the returned curl_example from the shell, then pass image_upload_ids. Never base64-encode a local photo into a tool call. A public http(s) URL: pass image_urls. Only a tiny generated image (under about 100 KB decoded) uses image_base64s. One upload can be attached to several records until it expires. image_mode defaults to append (add to the existing photos); replace swaps them all out; remove_image_ids deletes specific ones (ids from image_ids). If any image fails, the update is rolled back. The attaching call still needs confirm: true.

The MCP tool is refused until it is called again with confirm: true. If the call errors or times out, read the task back before retrying.

put/tasks/{id}

Request

  • Base URL: https://api.purplegrain.com/api/v1
  • URL: https://api.purplegrain.com/api/v1/tasks/{id}
  • Auth: HTTP bearer

Path parameters

idstring required

Id of the record

Query parameters

includestring
Example:producer,provider,service

Comma-separated snake_case relationship paths to embed (JSON:API included array, or inlined for application/json). Never embedded by default; unknown paths ignored; dot notation selects children; max 10 paths. Allowed paths: producer, provider, category, place, place.location, service, service.owner, service.category, service.city, service.place, service.location, farm, parent, children, asset.

Request body

Response

Update. When the include query parameter is used, the response may contain an included array (JSON:API) or inlined related resources (application/json).

Example response

{
  "data": {
    "type": "task"
  }
}

Changes

No recorded changes to this operation across all 2 revisions of this API.