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

# Update Paddock Boundary

`PUT /paddocks/{id}/boundary`

## Request

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

Save (or clear) a paddock's outline.

A dedicated endpoint rather than attributes on `updatePaddock`, because
it is the single place two rules are enforced:

* **A typed area is never overwritten by a drawn one.**
  `area_source: "drawn"` recomputes `area_ha` from the ring;
  `area_source: "typed"` saves the ring and leaves `area_ha` exactly as
  it is. A request that names no source keeps the paddock's own, so
  omitting the field can never clobber a typed number; a paddock that has
  never had one gets `drawn`.
* **Geometry is repaired before it is measured.** Rings are validated
  (at least 4 positions, closed, finite, latitude within ±90 and
  longitude within ±180), repaired with `ST_MakeValid`, wound
  counter-clockwise and stored as a MultiPolygon — so a self-crossing
  ring cannot report a plausible-but-wrong hectare figure. The geometry
  read back may therefore be reordered or split into parts.

* **A paddock ring must be near its property.** A ring whose centroid
  lies more than 25 km from the property's map point (`centroid_lat` /
  `centroid_lon` on the farm) is refused with a 422 that names the
  distance — with no imagery under the editor, that is the ring drawn
  over the wrong ground. A property with no map point yet is not
  guarded.

Area is computed by PostGIS as `ST_Area(geography)` in hectares. A
paddock carries no map point of its own — it inherits its property's, and
the point its name is drawn at is the ring's mean.

**Provenance.** `boundary_source` (traced | grid | gps | imported) is
the client's claim about how the ring was captured and travels with it;
`boundary_captured_by` is stamped server-side from the acting user and
is never accepted from the request. Both are cleared with the ring.

**The diary.** When the save changes `area_ha` — a first ring measured
under `drawn`, a redraw that measures differently, or a cleared ring
that takes a measured area with it — one completed observation is filed
on the paddock in the same transaction ("Boundary redrawn — area 70 ha,
was 84 ha"; "Boundary drawn — area 70 ha"; "Boundary removed — was
84 ha"), through the same path a rename or a typed area change uses. A
ring that measures the same, or one saved over a typed area, writes
nothing. Requires organization edit rights.

## Path parameters

- `id` string, required

## Query parameters

- `include` string

## Request body

- PaddockBoundaryModelAttributes: Flat attributes-adapter request body (Content-Type application/json) for the paddock boundary. The same fields hoisted directly under `data` (no nested `attributes` envelope). Equivalent JSON:API (nested) shape: `PaddockBoundaryModel` sent as application/vnd.api+json.
  - `data` object, required
    - `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 position repeated last. Not a GeoJSON object. Omit the key to leave the stored geometry untouched; send `null` to clear it.
      - array[]: One closed exterior ring.
        - number[]: [longitude, latitude]
    - `area_source` 'typed' | 'drawn', nullable: `drawn` recomputes `area_ha` from the ring; `typed` leaves `area_ha` untouched. Omitted, the paddock's own source stands.
    - `boundary_source` 'traced' | 'grid' | 'gps' | 'imported', nullable: How the ring being saved was captured. Provenance describes THIS ring: omitted alongside a new `boundary`, the stored source is reset to null rather than carried over from the ring it replaced; sent without a `boundary`, it corrects the stored ring's source in place. Cleared with the ring. `boundary_captured_by` is not accepted — the server stamps it from the acting user.

## Response `200`

The paddock with its saved boundary.

- 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
    - `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.
    - `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
    - `farm` object: Present when include=farm
  - `meta` PaginationMeta
    - `current_page` number
    - `next_page` number, nullable
    - `prev_page` number, nullable

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: A ring with fewer than 4 positions, an unclosed ring, a coordinate out of range, geometry that cannot be repaired into a polygon, a ring whose centroid is more than 25 km from the property's map point, or an unknown `boundary_source`

---

[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/4bedbc1c784c?raw)