> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.definitely.live/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.definitely.live/_mcp/server.

# Plant Catalog Management Guide

This guide walks you through managing the plant inventory catalog using the REST API endpoints.

---

## 1. Adding a New Plant

To add a plant item to the inventory catalog, send a `POST` request to `/plant` with the required metadata schema.

```json title="Request Payload (POST /v3/plant)"
{
  "id": 10,
  "name": "Ficus Elastica (Rubber Tree)",
  "category": {
    "id": 1,
    "name": "Indoor Trees"
  },
  "photoUrls": [
    "https://assets.plantstore.dev/images/ficus-elastica-1.jpg",
    "https://assets.plantstore.dev/images/ficus-elastica-2.jpg"
  ],
  "tags": [
    {
      "id": 101,
      "name": "easy-care"
    },
    {
      "id": 102,
      "name": "bright-indirect-light"
    }
  ],
  "status": "available"
}
```

### Code Example

```bash title="cURL"
curl -X POST "https://api.plantstore.dev/v3/plant" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <OAUTH2_TOKEN>" \
  -d '{
    "id": 10,
    "name": "Ficus Elastica",
    "photoUrls": ["https://assets.plantstore.dev/images/ficus.jpg"],
    "status": "available"
  }'
```

```python title="Python"
import requests

headers = {
    "Authorization": "Bearer <OAUTH2_TOKEN>",
    "Content-Type": "application/json"
}
data = {
    "id": 10,
    "name": "Ficus Elastica",
    "photoUrls": ["https://assets.plantstore.dev/images/ficus.jpg"],
    "status": "available"
}

response = requests.post("https://api.plantstore.dev/v3/plant", json=data, headers=headers)
print(response.json())
```

---

## 2. Searching & Filtering Plants

### Search by Status

Retrieve all plants matching specific inventory statuses (`available`, `pending`, `sold`):

```http
GET /v3/plant/findByStatus?status=available,pending HTTP/1.1
Host: api.plantstore.dev
Accept: application/json
```

```json title="Response Payload (200 OK)"
[
  {
    "id": 10,
    "name": "Ficus Elastica (Rubber Tree)",
    "status": "available"
  },
  {
    "id": 12,
    "name": "Monstera Deliciosa",
    "status": "pending"
  }
]
```

### Search by Tags

Find plants based on one or more category tags:

```http
GET /v3/plant/findByTags?tags=easy-care,pet-friendly HTTP/1.1
Host: api.plantstore.dev
Accept: application/json
```

---

## 3. Uploading Plant Images

Attach high-resolution product photographs to an existing plant record via `POST /plant/{plantId}/uploadImage`:

```bash title="Upload Image via multipart/form-data"
curl -X POST "https://api.plantstore.dev/v3/plant/10/uploadImage" \
  -H "Authorization: Bearer <OAUTH2_TOKEN>" \
  -F "additionalMetadata=High-res product photo" \
  -F "file=@/path/to/ficus.jpg"
```

```json title="Response Payload"
{
  "code": 200,
  "type": "SUCCESS",
  "message": "additionalMetadata: High-res product photo\nFile uploaded to https://assets.plantstore.dev/images/upload_10.jpg"
}
```

---

## 4. Updating & Deleting Plants

* **Update Existing Plant**: `PUT /plant` (updates all plant attributes).
* **Update Status via Form Data**: `POST /plant/{plantId}` (updates `name` and `status` via URL-encoded form data).
* **Delete Plant**: `DELETE /plant/{plantId}` (requires valid `api_key` or `write:plants` scope).

Deleting a plant that has active `pending` orders will result in a `409 Conflict` error. Ensure all orders are completed or cancelled prior to deleting plant inventory.