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

> Create a per-plant record under a block. Tag IDs are unique within a block.

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

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

<ParamField body="label" type="string" required>
  1–100 characters. Within-block identifier (e.g. `"Row 1, Tree 4"`, `"P-0001"`).
</ParamField>

<ParamField body="tagId" type="string">
  1–200 characters. QR / RFID / barcode identifier. **Unique within the block** — duplicate returns `409 CONFLICT`.
</ParamField>

<ParamField body="position" type="object">
  `{ lat: number, lng: number }`. GPS position. Pass `null` to clear.
</ParamField>

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

<ParamField body="status" type="string" default="alive">
  One of `alive`, `sick`, `dead`, `replaced`, `removed`.
</ParamField>

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

### Response

Returns the created plant wrapped under `data`.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://www.wiseyield.co/api/v1/farms/11111111.../fields/88888888.../blocks/aaaaaaaa.../plants' \
    -H "Authorization: Bearer $WISEYIELD_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "label": "Row 1, Tree 4",
      "tagId": "QR-MDJ-0247",
      "position": { "lat": 30.0444, "lng": 31.2357 },
      "plantedAt": "2024-03-15T00:00:00.000Z",
      "status": "alive"
    }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    `https://www.wiseyield.co/api/v1/farms/${farmId}/fields/${fieldId}/blocks/${blockId}/plants`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.WISEYIELD_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        label: 'Row 1, Tree 4',
        tagId: 'QR-MDJ-0247',
        position: { lat: 30.0444, lng: 31.2357 },
      }),
    }
  );
  const { data: plant } = await res.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "data": {
      "id": "ffffffff-1111-2222-3333-444444444444",
      "blockId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "label": "Row 1, Tree 4",
      "tagId": "QR-MDJ-0247",
      "position": { "lat": 30.0444, "lng": 31.2357 },
      "plantedAt": "2024-03-15T00:00:00.000Z",
      "status": "alive",
      "createdAt": "2026-05-17T17:20:00.000Z"
    }
  }
  ```

  ```json 409 Tag conflict theme={null}
  {
    "error": "Conflict",
    "code": "CONFLICT",
    "message": "Tag ID \"QR-MDJ-0247\" is already assigned to another plant in this block"
  }
  ```
</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, or block doesn't exist or belongs to another user |
| `409 CONFLICT`            | `tagId` already exists for another plant in this block         |
| `429 RATE_LIMIT_EXCEEDED` | Per-user rate limit reached                                    |
| `5xx`                     | Server error                                                   |