---
title: "Rename a block or change its paddocks"
method: PATCH
path: "/properties/{property_id}/blocks/{id}"
tags: ["Blocks"]
---

# Rename a block or change its paddocks

`PATCH /properties/{property_id}/blocks/{id}`

## Request

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

Renames a block, changes its kind or number, or (with `paddock_ids`) replaces its members: the listed live paddocks of the property move into it (out of any other block), and a member left out goes back to the home block (`block_id` null). Omitting `paddock_ids` leaves the members alone. Writes, moves or removes no record. To move one paddock, `updatePaddock` with `block_id` also works. Requires edit rights on the property.

## Path parameters

- `property_id` string, uuid, required
- `id` string, uuid, required

## Request body

- BlockUpdateModelAttributes: Flat attributes-adapter request body (Content-Type application/json). Every field is optional. Equivalent JSON:API shape: `BlockUpdateModel`.
  - `data` object, required
    - `name` string
    - `kind` 'outblock' | 'irrigation_farm' | 'management'
    - `block_number` string, nullable
    - `paddock_ids` string[]

## Response `200`

The updated block.

- BlockResponseAttributes: One block in attributes-adapter shape (Accept application/json).
  - `data` object: A block's fields, as the block write endpoints answer them.
    - `id` string, uuid
    - `type` string
    - `name` string
    - `kind` 'outblock' | 'irrigation_farm' | 'management'
    - `block_number` string, nullable
    - `property_id` string, uuid
    - `paddock_ids` string[]
    - `area_ha` number, nullable
    - `hull` object, nullable
      - `type` string
      - `coordinates` unknown[]
        - unknown
    - `archived_at` string, date-time, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `401`: Unauthorized — no session.
- `403`: Forbidden — the caller may not edit this property.
- `404`: No such property, or no live block with that id on it.
- `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 duplicate name, an unknown kind, or a `paddock_ids` entry that is not a live paddock of this property.

## Changes

- **2026-10-30** `143d65e52617`: 2 info
  - added the non-success response with the status `409`
  - added the non-success response with the status `415`
- **2026-10-30** `92c4663a1266`: 24 warning, 24 info
  - removed the optional property `_meta` from the response with the `401` status (media type: application/json)
  - removed the optional property `_meta` from the response with the `401` status (media type: application/vnd.api+json)
  - removed the optional property `_meta` from the response with the `403` status (media type: application/json)
  - removed the optional property `_meta` from the response with the `403` status (media type: application/vnd.api+json)
  - …44 more
- **2026-10-30** `c1bc18b1cdbc`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/purplegrain/apis/purple-grain-api/changes/properties/:property_id/blocks/: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)