Drench records

Create Drench Record

Deprecated alias for recording a drench on one mob. The app and an API key can still call it. An AI assistant cannot: the response is 403 with detail "An AI assistant cannot call this." An assistant records a drench with createTreatmentRecord and category drench.

Creates the one task that is the record and answers with that task, drench included, exactly as GET /tasks/{id} would. The server sets the producer from the farm's owner, operation_type to treatment, capture_source to agent, operator from the signed-in user, and the treatment category to drench. head defaults to the mob's current head count. A mob with no head count yet takes the head recorded as its count; a count already set is never changed. date (YYYY-MM-DD) defaults to today and is stored as midday in the application time zone; a future date creates the open task (status: pending, created_as: task) instead of a completed record.

Send one products entry per product (name, active, batch, dose, whp_days, esi_days, and expiry and the dose parts when the farmer stated them). If the label has no ESI, send the WHP number as esi_days. This alias does not take category or route. A completed record with no product row is refused (422, "A drench needs at least one product").

Photos travel the same way as on a treatment (image_upload_ids, image_urls, image_base64s). If any image fails, the whole create is rolled back.

Example (application/vnd.api+json):

{
  "data": {
    "type": "drench-record",
    "attributes": {
      "date": "2025-12-23",
      "head": 11,
      "description": "Drench rams",
      "products": [
        {
          "name": "Startect",
          "batch": "728661",
          "dose": "20 mL per head",
          "whp_days": 14,
          "esi_days": 28
        }
      ]
    }
  }
}

Photos. A file on disk is staged with createImageUpload, whose curl_example PUTs the bytes, and attached with 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. On update, image_mode defaults to append (add to the existing photos); replace swaps them all out; remove_image_ids deletes specific ones. If any image fails, the whole create or update is rolled back. The attaching call still needs confirm: true. createImageUpload and its PUT do not.

post/mobs/{mob_id}/drench-records

Request

  • Base URL: https://api.purplegrain.com/api/v1
  • URL: https://api.purplegrain.com/api/v1/mobs/{mob_id}/drench-records
  • Auth: HTTP bearer

Path parameters

mob_idstring required

The mob that was drenched.

Headers

Idempotency-Keystring

Optional. Send the same value when retrying a create after a 502 or 504. The same user, path and key returns the original result instead of writing a second one. The key is kept for 24 hours.

Request body

Example request

{
  "data": {
    "date": "2025-12-23",
    "description": "Drench rams"
  }
}

Response

Created. The task, with its drench.

Example response

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

Changes

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