> ## 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.

# Create block

> Create a block on a field. Block must belong to a crop that already lives on the field.

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

### 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>

### Request body

<ParamField body="cropId" type="string" required>
  UUID of the crop. Must belong to `fieldId` (so the block is consistent with the field's planting).
</ParamField>

<ParamField body="name" type="string" required>1–200 characters.</ParamField>

<ParamField body="varietyId" type="string">UUID of an admin variety record. Pulls spacing / density defaults if provided.</ParamField>

<ParamField body="description" type="string">Up to 2,000 characters.</ParamField>

<ParamField body="plantingDate" type="string">ISO 8601 datetime.</ParamField>

<ParamField body="plantCount" type="integer">1–1,000,000.</ParamField>

<ParamField body="spacingX" type="number">Row spacing in meters, 0–10,000.</ParamField>

<ParamField body="spacingY" type="number">Plant spacing in meters, 0–10,000.</ParamField>

<ParamField body="plantDensity" type="number">Plants per hectare, 0–1,000,000.</ParamField>

<ParamField body="area" type="number">Block area, 0–1,000,000 (in the farm's `areaUnit`).</ParamField>

<ParamField body="geometry" type="object">
  GeoJSON `Polygon` or `Point` covering the block. Polygon: `{ type: "Polygon", coordinates: number[][][] }`. Point: `{ type: "Point", coordinates: [lng, lat] }`.
</ParamField>

<ParamField body="plantingGrid" type="object">
  Grid metadata. `{ pattern: "square" | "hexagonal" | "triangular" | "custom", rowCount, columnCount, rowOrientation, originLatLng: [lat, lng] }`.
</ParamField>

<ParamField body="status" type="string" default="planned">
  One of `planned`, `planted`, `established`, `mature`, `declined`, `harvested`, `removed`.
</ParamField>

<ParamField body="notes" type="string">Up to 5,000 characters.</ParamField>

### Response

Returns the created block wrapped under `data`.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://www.wiseyield.co/api/v1/farms/11111111.../fields/88888888.../blocks' \
    -H "Authorization: Bearer $WISEYIELD_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "cropId": "33333333-4444-5555-6666-777777777777",
      "name": "North block — Medjool",
      "plantingDate": "2024-03-15T00:00:00.000Z",
      "plantCount": 60,
      "spacingX": 10,
      "spacingY": 10,
      "status": "mature"
    }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    `https://www.wiseyield.co/api/v1/farms/${farmId}/fields/${fieldId}/blocks`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.WISEYIELD_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        cropId, name: 'North block — Medjool',
        plantCount: 60, spacingX: 10, spacingY: 10,
      }),
    }
  );
  const { data: block } = await res.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "data": {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "cropId": "33333333-4444-5555-6666-777777777777",
      "fieldId": "88888888-9999-aaaa-bbbb-cccccccccccc",
      "name": "North block — Medjool",
      "plantCount": 60,
      "spacingX": "10",
      "spacingY": "10",
      "status": "planned",
      "createdAt": "2026-05-17T17:10:00.000Z"
    }
  }
  ```

  ```json 404 Crop not on field theme={null}
  { "error": "Not found", "code": "NOT_FOUND", "message": "Crop not found on this field" }
  ```
</ResponseExample>

## Errors

| Status                    | When                                                                                                 |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `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, or `cropId` doesn't exist, is soft-deleted, or doesn't belong to the resolved hierarchy |
| `429 RATE_LIMIT_EXCEEDED` | Per-user rate limit reached                                                                          |
| `5xx`                     | Server error                                                                                         |