---
title: "Update Paddock"
method: PATCH
path: "/paddocks/{id}"
tags: ["Paddocks"]
---

# Update Paddock

`PATCH /paddocks/{id}`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/paddocks/{id}`
- Auth: HTTP bearer

Renaming a paddock, or changing its area, land use or crop, writes a
record on its timeline — "Renamed from North Block · Area set to 90 ha —
was 84 ha" — composed on the server, because three write surfaces edit a
paddock and only the server sees before and after atomically. An update
that changes none of those four fields writes nothing.

**Archive and restore are this endpoint**: `archived: true` hides the
paddock from the map and the lists while its records stay on the
property; `archived: false` brings it back. There is no `/archive` route.
Archiving writes no record.

**`block_id` moves the paddock between blocks**: a live block of the
same property puts it in that block, `null` takes it out to the home
block. It writes no record. To regroup several paddocks at once use
`updateBlock` with `paddock_ids`.

The owning property cannot be changed — a `property` relationship sent here
is ignored, so a paddock can never be re-parented and take its records
with it. `boundary` is not accepted; see `updatePaddockBoundary`.

Requires organization edit rights.

## Path parameters

- `id` string, required

## Query parameters

- `include` string

## Request body

- PaddockUpdateModelAttributes: Flat attributes-adapter request body (Content-Type application/json). Attribute fields live directly under `data` (no nested `attributes` envelope). Every field is optional — a partial write. Equivalent JSON:API (nested) shape: `PaddockUpdateModel` sent as application/vnd.api+json.
  - `data` object, required
    - `name` string
    - `area_ha` number, nullable
    - `area_source` 'typed' | 'drawn', nullable
    - `land_use` 'cropping' | 'grazing' | 'mixed' | 'fallow', nullable
    - `tenure` string, nullable: Stored lowercase. owned or leased. Blank leaves it unset.
    - `current_crop` string, nullable
    - `archived` boolean, nullable: `true` archives the paddock, `false` restores it.
    - `block_id` string, uuid, nullable: Puts the paddock in a live block of the same property, or `null` to take it out. Writes no record.
    - `parcel_id` string, uuid, nullable: A parcel already attached to this property, or null to clear it.

## Response `200`

Updated

- PaddocksShowResponseAttributes
  - `data` PaddockModelAttributes: Single paddock in attributes-adapter shape (Accept application/json).
    - `id` string
    - `type` string
    - `slug` string: Unique within its parent (a property per owner; a paddock or mob per property); generated from the name and renamed with it. The old slug keeps resolving. See `resolveLink`.
    - `web_path` string: The address on the web. Present when read directly.
    - `url` string: The whole link; carries the property's `?share=` token when it is shared by link. Present when read directly.
    - `name` string
    - `area_ha` number, nullable: Paddock area in hectares. Measured from the boundary when `area_source` is `drawn`; the farmer's own number when it is `typed`.
    - `area_source` 'typed' | 'drawn', nullable: Where `area_ha` came from. A `typed` area is never overwritten by a drawn one.
    - `land_use` 'cropping' | 'grazing' | 'mixed' | 'fallow', nullable
    - `tenure` 'owned' | 'leased', nullable: Whether the area is owned or leased. Null when unset.
    - `current_crop` string, nullable
    - `boundary` array[], nullable: The paddock outline: an array of rings, each ring an array of `[longitude, latitude]` pairs in RFC 7946 order — **longitude first** — with at least 4 positions and the first repeated last. Not a GeoJSON object (see `PaddockBoundaryModel`).
      - array[]: One closed exterior ring.
        - number[]: [longitude, latitude]
    - `has_boundary` boolean: Whether the paddock has an outline at all — the cheap face of `boundary`.
    - `withholding` object, nullable: Is the paddock under a grazing or harvest withholding period right now? The latest spray record whose graze or harvest date is still ahead, or null. **Derived, not stored.** Read-only. Served on the paddock's own read and on lists (SPRAY_RECORD.md).
      - `task_id` string
      - `record_id` string: The SprayRecord id.
      - `safe_to_graze_on` string, date, nullable
      - `safe_to_harvest_on` string, date, nullable
      - `products` string[]
    - `boundary_captured_at` string, date-time, nullable
    - `boundary_source` 'traced' | 'grid' | 'gps' | 'imported', nullable: How the ring was captured — traced over imagery, placed on the grid with no imagery, walked with the phone's GPS, or read from a KML/shapefile. Null for a ring saved before provenance was recorded or by a caller that named no source. Written with the ring and cleared with it.
    - `boundary_captured_by` string, nullable: Id of the user who saved the ring, stamped server-side from the request's actor and never accepted from a client. Null when a machine token saved it, and null while the paddock has no ring.
    - `archived` boolean: An archived paddock leaves the map and the lists; its records stay on the property.
    - `archived_at` string, date-time, nullable
    - `block_id` string, uuid, nullable: The block the paddock sits in. Null in the home block.
    - `parcel_id` string, uuid, nullable: The cadastral parcel this paddock sits in. Null until one is attached to the property and chosen here.
    - `record_count` integer: Completed rows on this paddock — its diary.
    - `open_task_count` integer: Pending rows on this paddock.
    - `last_record_at` string, date-time, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `property` object: Present when include=property
  - `meta` PaginationMeta
    - `current_page` number
    - `next_page` number, nullable
    - `prev_page` number, nullable

## Other responses

- `400`: The `include` query parameter names a relationship path this endpoint does not take (JSON:API 1.1, "Inclusion of Related Resources"). One error with `code: "unknown_include"` and `source.parameter: "include"`; its `detail` names the refused path(s) and the paths the endpoint allows (the parameter's `x-include-paths`). An endpoint whose serializer whitelists no relationship refuses any path. Rolling out as monitor then enforce: until the API's `JSONAPI_UNKNOWN_INCLUDE` is `reject`, an unknown path is dropped and logged instead.
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict — the JSON:API request document names a different resource from the URL (JSON:API 1.1 §9.2 and §9.3). `errors[0].code` is `type_mismatch` when `data.type` is not one of this endpoint's resource types (`source.pointer` is `/data/type`), or `id_mismatch` when, on an update, `data.id` is not the id in the URL (`/data/id`). Only a body sent as `application/vnd.api+json` is checked; the flat `application/json` body has no resource object. Nothing was changed. Request validation runs first: a `data.type` outside the operation's documented enum, or missing where the schema requires it, is a `400` before this check, so the 409 is seen where the documented type is a free string, or when validation is off.
- `415`: Unsupported Media Type — the request's `Content-Type` is `application/vnd.api+json` with a media type parameter the JSON:API media type does not allow (anything other than `ext` and `profile`; `; charset=utf-8` is the usual one). Send the bare media type. The error's `code` is `unsupported_media_type` and `source.header` is `Content-Type`. Until the switch is on (`JSONAPI_CONTENT_TYPE_PARAMS=reject`) such a request is let through and logged; the operation documents the response it will have.
- `422`: A blank name, a name already used on the property (live or archived), or an unknown land use

## Changes

- **2026-10-30** `e32f34ba218b`: 1 info
  - added the optional property `data/relationships/block` to the response with the `200` status
- **2026-10-30** `143d65e52617`: 3 info
  - added the non-success response with the status `400`
  - added the non-success response with the status `409`
  - added the non-success response with the status `415`
- **2026-10-30** `92c4663a1266`: 12 warning, 12 info
  - removed the optional property `_meta` from the response with the `404` status (media type: application/json)
  - removed the optional property `_meta` from the response with the `404` status (media type: application/vnd.api+json)
  - removed the optional property `_meta` from the response with the `422` status (media type: application/json)
  - removed the optional property `_meta` from the response with the `422` status (media type: application/vnd.api+json)
  - …20 more
- **2026-10-30** `c1bc18b1cdbc`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/purplegrain/apis/purple-grain-api/changes/paddocks/:id/patch.md)

---

[API](https://skmtc.dev/purplegrain/apis/purple-grain-api.md) - [All operations](https://skmtc.dev/purplegrain/apis/purple-grain-api/llms.txt) - [OpenAPI document](https://skmtc.dev/purplegrain/apis/purple-grain-api/revisions/370fe2f3ed4f?raw)