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

> Create a field on a farm owned by the authenticated user.

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

### Authentication

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

### Path parameters

<ParamField path="id" type="string" required>
  Farm UUID.
</ParamField>

### Request body

<ParamField body="name" type="string" required>1–200 characters.</ParamField>
<ParamField body="area" type="number | string" required>Positive number in the farm's `areaUnit`.</ParamField>
<ParamField body="description" type="string">Up to 2,000 characters.</ParamField>
<ParamField body="boundaries" type="object">GeoJSON `Polygon` (`{ type: "Polygon", coordinates: number[][][] }`).</ParamField>
<ParamField body="soilType" type="string">Up to 100 characters.</ParamField>
<ParamField body="soilPh" type="number | string">Soil pH.</ParamField>
<ParamField body="status" type="string" default="active">One of `active`, `fallow`, `preparing`, `planted`.</ParamField>
<ParamField body="notes" type="string">Up to 5,000 characters.</ParamField>

### Response

Returns the created field wrapped under `data`. See [List fields](/api-reference/fields/list-fields) for the full field reference.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://www.wiseyield.co/api/v1/farms/11111111-2222-3333-4444-555555555555/fields' \
    -H "Authorization: Bearer $WISEYIELD_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "name": "North Field", "area": 4.2, "soilType": "sandy loam", "status": "active" }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    `https://www.wiseyield.co/api/v1/farms/${farmId}/fields`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.WISEYIELD_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ name: 'North Field', area: 4.2 }),
    }
  );
  const { data: field } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests
  res = requests.post(
      f'https://www.wiseyield.co/api/v1/farms/{farm_id}/fields',
      headers={
          'Authorization': f"Bearer {os.environ['WISEYIELD_API_KEY']}",
          'Content-Type': 'application/json',
      },
      json={'name': 'North Field', 'area': 4.2},
  )
  field = res.json()['data']
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "data": {
      "id": "88888888-9999-aaaa-bbbb-cccccccccccc",
      "farmId": "11111111-2222-3333-4444-555555555555",
      "name": "North Field",
      "area": "4.2",
      "soilType": "sandy loam",
      "status": "active",
      "createdAt": "2026-05-17T17:00:00.000Z"
    }
  }
  ```

  ```json 400 Validation failed theme={null}
  {
    "error": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": {
      "area": ["Area must be a positive number"],
      "name": ["Name is required"]
    }
  }
  ```
</ResponseExample>

## Errors

| Status                    | When                                                          |
| ------------------------- | ------------------------------------------------------------- |
| `400 VALIDATION_ERROR`    | Body validation failed (`details` carries per-field messages) |
| `401`                     | Missing, malformed, expired, or revoked API key               |
| `403 INSUFFICIENT_SCOPE`  | Key lacks `fields:write` scope                                |
| `404 NOT_FOUND`           | Farm doesn't exist or is not owned by the user                |
| `429 RATE_LIMIT_EXCEEDED` | Per-user rate limit reached                                   |
| `5xx`                     | Server error                                                  |