> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wiseyield.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Update block

> Update mutable fields on a block. Only provided fields are touched.

```
PUT https://www.wiseyield.co/api/v1/farms/{id}/fields/{fieldId}/blocks/{blockId}
```

### Authentication

Requires a key with the `fields:write` scope.

### Path parameters

<ParamField path="id" type="string" required>Farm UUID.</ParamField>
<ParamField path="fieldId" type="string" required>Field UUID.</ParamField>
<ParamField path="blockId" type="string" required>Block UUID.</ParamField>

### Request body

All fields are optional. Only fields you include in the body are updated. To re-parent the block to a different crop, the new `cropId` must belong to the same field.

<ParamField body="cropId" type="string">UUID. Must belong to the block's current field.</ParamField>
<ParamField body="varietyId" type="string">UUID. Pass `null` to clear.</ParamField>
<ParamField body="name" type="string">1–200 characters.</ParamField>
<ParamField body="description" type="string">Up to 2,000 characters. Pass `null` to clear.</ParamField>
<ParamField body="plantingDate" type="string">ISO 8601 datetime. Pass `null` to clear.</ParamField>
<ParamField body="plantCount" type="integer">1–1,000,000. Pass `null` to clear.</ParamField>
<ParamField body="spacingX" type="number">0–10,000 meters. Pass `null` to clear.</ParamField>
<ParamField body="spacingY" type="number">0–10,000 meters. Pass `null` to clear.</ParamField>
<ParamField body="plantDensity" type="number">0–1,000,000 plants/ha. Pass `null` to clear.</ParamField>
<ParamField body="area" type="number">0–1,000,000. Pass `null` to clear.</ParamField>
<ParamField body="status" type="string">One of `planned`, `planted`, `established`, `mature`, `declined`, `harvested`, `removed`.</ParamField>
<ParamField body="notes" type="string">Up to 5,000 characters. Pass `null` to clear.</ParamField>

### Response

Returns the updated block wrapped under `data`.

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT 'https://www.wiseyield.co/api/v1/farms/11111111.../fields/88888888.../blocks/aaaaaaaa...' \
    -H "Authorization: Bearer $WISEYIELD_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "status": "harvested" }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "status": "harvested",
      "updatedAt": "2026-05-17T17:15:00.000Z"
    }
  }
  ```
</ResponseExample>

## Errors

| Status                    | When                                                                                          |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| `400 INVALID_ID`          | Any path UUID is malformed                                                                    |
| `400 VALIDATION_ERROR`    | Body validation failed                                                                        |
| `401`                     | Missing, malformed, expired, or revoked API key                                               |
| `403 INSUFFICIENT_SCOPE`  | Key lacks `fields:write` scope                                                                |
| `404 NOT_FOUND`           | Farm, field, block, or new `cropId` doesn't exist or doesn't belong to the resolved hierarchy |
| `429 RATE_LIMIT_EXCEEDED` | Per-user rate limit reached                                                                   |
| `5xx`                     | Server error                                                                                  |