---
title: "Update Property (deprecated PUT alias)"
method: PUT
path: "/properties/{id}"
tags: ["Properties"]
deprecated: true
---

# Update Property (deprecated PUT alias)

`PUT /properties/{id}`

## Request

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

> **Deprecated.**

Alias of PATCH `/properties/{id}` (`updateProperty`); JSON:API updates are PATCH. PUT stays routed for existing clients.

## Path parameters

- `id` string, required

## Query parameters

- `include` string

## Request body

- PropertyUpdateModelAttributes: Flat attributes-adapter request body (Content-Type application/json). Attribute fields and relationships live directly under `data` (no nested `attributes` / `relationships` envelopes). Each relationship is a resource identifier object ({ id, type }). Equivalent JSON:API (nested) shape: `PropertyUpdateModel` sent as application/vnd.api+json.
  - `data` object, required
    - `visibility` 'private' | 'link' | 'public': Who can see the property and, through it, its paddocks, mobs and scoped task lists. `private` (default) is members only; `link` is anyone with the share token (`?share=`); `public` is anyone and search engines.
    - `name` string
    - `location` string, nullable
    - `pic` string, nullable: Property Identification Code. Blank or null leaves it unset. A value is stripped and stored uppercase. Eight letters or digits; lowercase is accepted. Not checked against `state`. One code per property.
    - `state` string, nullable: Not stored. The state on a read is taken from place_label or location. A value sent here is ignored.
    - `livestock_not_required` boolean, nullable: Set true only when the farmer says this property has no livestock for now. False/null undo the choice. Skips only mobs, never the first completed typed record; no mob is created.
    - `reef_catchment` boolean, nullable: Whether the property is in a Queensland reef catchment. Not inferred. Accepted whatever state is.
    - `size` string, nullable
    - `place_label` string, nullable: The geocoded label shown under the property name on the map. Distinct from `location` (the settings "Town, State" caption).
    - `centroid_lat` number, nullable: Latitude of the point the map opens on. Send both `centroid_lat` and `centroid_lon`, or neither — a half pair is rejected. A property with no boundary still needs a point ("Nothing on the map yet").
    - `centroid_lon` number, nullable: Longitude of the point the map opens on. Send both `centroid_lat` and `centroid_lon`, or neither.

## Response `200`

Updated

- PropertiesShowResponseAttributes
  - `data` PropertyModelAttributes: Single property 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`.
    - `visibility` 'private' | 'link' | 'public': Who can see the property and, through it, its paddocks, mobs and scoped task lists. `private` (default) is members only; `link` is anyone with the share token (`?share=`); `public` is anyone and search engines.
    - `web_path` string: The property's address on the web, e.g. `/organizations/hillcrest/properties/yarrabee`. Present on a property read directly.
    - `url` string: The whole link to hand someone; for a property shared by link it carries `?share=<token>`. Present on a property read directly.
    - `can_edit` boolean: Whether the caller may change the property. From the session's role, never the address. Present on a property read directly.
    - `share_token` string, nullable: The token behind `visibility=link`. Returned only to callers who can change who sees the property.
    - `name` string
    - `location` string, nullable
    - `pic` string, nullable: Property Identification Code. One state-issued code of 8 letters or digits, stored uppercase. Null when unset. Not checked against `state`. A property stores one PIC. Private: present only for callers authorized to read this property's private records. Omitted for public or share-token access alone, including signed-in non-members.
    - `state` 'NSW' | 'VIC' | 'QLD' | 'SA' | 'WA' | 'TAS' | 'NT' | 'ACT', nullable: Read from place_label, or from location when place_label is blank. Null when the address does not name a state.
    - `livestock_not_required` boolean, nullable: Explicit farmer choice to skip mobs for this property during onboarding. True means no livestock needed for now; false/null undo the choice. Never inferred from zero mobs. Does not skip the first real record. Returned only with private-record permission, not public/share access.
    - `reef_catchment` boolean, nullable: Whether the farmer says the property is in a Queensland reef catchment. Not inferred from `state`, and accepted for any state. Null when unset.
    - `size` string, nullable
    - `place_label` string, nullable: The geocoded label shown under the property name on the map, e.g. "1180 Kywong Road, Currawarna NSW 2650".
    - `centroid_lat` number, nullable: Latitude of the point the map opens on. Present exactly when `centroid_lon` is.
    - `centroid_lon` number, nullable: Longitude of the point the map opens on. Present exactly when `centroid_lat` is.
    - `boundary` array[], nullable: The property 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 `PropertyBoundaryModel`).
      - array[]: One closed exterior ring.
        - number[]: [longitude, latitude]
    - `boundary_captured_at` string, date-time, nullable: When the boundary was last saved. Null while the property has no ring.
    - `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 property has no ring.
    - `area_ha` number, nullable: Property 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.
    - `paddock_count` integer: How many LIVE paddocks the property has. Archived paddocks are not counted.
    - `mob_count` integer: How many LIVE mobs the property has. Archived mobs are not counted.
    - `blocks` PropertyBlock[]: The property's live blocks. Empty when every paddock is in the home block.
      - `id` string, uuid
      - `name` string
      - `kind` 'outblock' | 'irrigation_farm' | 'management'
      - `block_number` string, nullable: An optional number the business uses for the block, such as "Farm 89".
      - `paddock_ids` string[]: The ids of the live paddocks in the block, ordered by paddock name. Each of those paddocks has this block's id as its `block_id`.
      - `area_ha` number, nullable: The sum of the member paddocks' areas, in hectares. Null when no member has an area.
      - `hull` object, nullable: The convex hull of the member paddocks' boundaries as a GeoJSON geometry (usually a Polygon) in [lng, lat]. Null when no member has a boundary. For the map's dashed outline; not a boundary of its own.
        - `type` string
        - `coordinates` unknown[]
          - unknown
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `organization` object: Present when include=organization
    - `user` object, nullable: The person who owns a personal property (linkage only); null on a business's property.
  - `meta` PaginationMeta
    - `current_page` number
    - `next_page` number, nullable
    - `prev_page` number, nullable
  - `_meta` OnboardingMeta
    - `onboarding` Onboarding: Where the account in scope is in setting up a farm. A suggestion: reads are never refused because a step is missing. `next_step` is null once every step is done.
      - `status` 'not_started' | 'in_progress' | 'complete'
      - `completed_steps` string[]
      - `next_step` 'create_team' | 'create_property' | 'map_boundaries' | 'map_paddocks' | 'create_blocks' | 'add_mobs' | 'first_record', nullable
      - `skill` string
      - `skill_url` string
      - `agent_hint` string: Plain-language instruction, including a short fallback the agent can follow without the skill.

## 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. A document with no `data.type` is accepted for now.
- `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`: Unprocessable Entity

## Changes

- **2026-10-30** `e32f34ba218b`: 1 info
  - added the optional property `data/relationships/owner` 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`: 2 info
  - api operation id `updateProperty` removed and replaced with `updatePropertyPut`
  - endpoint deprecated
- …earlier changes not shown

[Operation history](https://skmtc.dev/purplegrain/apis/purple-grain-api/changes/properties/:id/put.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/e32f34ba218b?raw)