# Ingredient Manipulation

The tomato endpoints handle acquiring, slicing, and squeezing tomatoes in the PizzaStack API.

## Acquiring Tomatoes

### POST /v1/tomato/acquire

Acquire a new tomato to work with. Every tomato gets a unique ID within your session.

```python
import requests

API_BASE = "https://api.tomatopy.pizza/v1"
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key",
    "X-Session-ID": "your-session-id"
}

# Acquire a San Marzano tomato
response = requests.post(f"{API_BASE}/tomato/acquire", headers=HEADERS, json={
    "variety": "San Marzano",
    "ripeness": 0.8,
    "weight": 150
})
tomato = response.json()

print(tomato["id"])        # "tom_abc123"
print(tomato["variety"])   # "San Marzano"
print(tomato["ripeness"])  # 0.8
print(tomato["weight"])    # 150
print(tomato["type"])      # "raw"
```

#### Request Body

| Field      | Type    | Required | Description                                            |
| ---------- | ------- | -------- | ------------------------------------------------------ |
| `variety`  | string  | yes      | Tomato variety (e.g., "San Marzano", "Roma", "Cherry") |
| `ripeness` | float   | yes      | Ripeness from 0.0 to 1.0                               |
| `weight`   | integer | yes      | Weight in grams                                        |

### Acquiring Multiple Tomatoes

```python
# Acquire several tomatoes for a batch
varieties = [
    {"variety": "San Marzano", "ripeness": 0.9, "weight": 150},
    {"variety": "Roma", "ripeness": 0.85, "weight": 120},
    {"variety": "Cherry", "ripeness": 0.8, "weight": 30}
]

tomatoes = []
for v in varieties:
    response = requests.post(f"{API_BASE}/tomato/acquire", headers=HEADERS, json=v)
    response.raise_for_status()
    tomatoes.append(response.json())
```

## Slicing Tomatoes

### POST /v1/tomato/slice

Slice one or more tomatoes. Slicing is required before tomatoes can be used in cooking operations for optimal quality.

```python
# Slice the acquired tomatoes
response = requests.post(f"{API_BASE}/tomato/slice", headers=HEADERS, json={
    "tomato_ids": [tomato["id"]],
    "method": "dice",
    "size": "medium",
    "consistency": "uniform"
})
sliced = response.json()

print(sliced["id"])           # "slc_def456"
print(sliced["method"])       # "dice"
print(sliced["piece_count"])  # 24
```

#### Request Body

| Field         | Type             | Required | Description                                      |
| ------------- | ---------------- | -------- | ------------------------------------------------ |
| `tomato_ids`  | array of strings | yes      | IDs of tomatoes to slice                         |
| `method`      | string           | yes      | Cutting method: "dice", "slice", "chop", "mince" |
| `size`        | string           | yes      | Piece size: "small", "medium", "large"           |
| `consistency` | string           | no       | "uniform" or "rough" (default: "uniform")        |

### Slicing Multiple Tomatoes Together

```python
# Slice multiple tomatoes in one call
tomato_ids = [t["id"] for t in tomatoes]

response = requests.post(f"{API_BASE}/tomato/slice", headers=HEADERS, json={
    "tomato_ids": tomato_ids,
    "method": "chop",
    "size": "small",
    "consistency": "rough"
})
sliced_batch = response.json()
```

## Squeezing Tomatoes

### POST /v1/tomato/squeeze

Extract juice from tomatoes. This produces a liquid ingredient that can be used differently from sliced tomatoes.

```python
# Squeeze tomatoes for juice
response = requests.post(f"{API_BASE}/tomato/squeeze", headers=HEADERS, json={
    "tomato_ids": [tomato["id"]],
    "pressure": 0.7
})
juice = response.json()

print(juice["id"])       # "jce_ghi789"
print(juice["volume"])   # 120  (ml)
print(juice["type"])     # "juice"
```

#### Request Body

| Field        | Type             | Required | Description                                               |
| ------------ | ---------------- | -------- | --------------------------------------------------------- |
| `tomato_ids` | array of strings | yes      | IDs of tomatoes to squeeze                                |
| `pressure`   | float            | yes      | Pressure from 0.0 to 1.0 (higher = more juice, less pulp) |

## Error Handling

```python
# Handle common errors
response = requests.post(f"{API_BASE}/tomato/acquire", headers=HEADERS, json={
    "variety": "San Marzano",
    "ripeness": 1.5,  # Invalid: must be 0.0 to 1.0
    "weight": 150
})

if response.status_code == 400:
    error = response.json()
    print(f"Validation error: {error['message']}")

# Handle missing authentication
response = requests.post(f"{API_BASE}/tomato/acquire", json={
    "variety": "Roma",
    "ripeness": 0.8,
    "weight": 100
})

if response.status_code == 401:
    print("Missing or invalid API key")
```

## Best Practices

1. **Check Response Status Codes**

   ```python
   response = requests.post(f"{API_BASE}/tomato/acquire", headers=HEADERS, json={
       "variety": "San Marzano",
       "ripeness": 0.8,
       "weight": 150
   })
   response.raise_for_status()
   tomato = response.json()
   ```
2. **Always Slice Before Cooking**

   Raw tomato IDs passed to `/cook/simmer` will silently degrade sauce quality. Always slice first.
3. **Store IDs for Later Use**

   ```python
   # Keep track of ingredient IDs for the pipeline
   tomato_id = tomato["id"]
   sliced_id = sliced["id"]
   ```

## Endpoint Reference

| Endpoint             | Method | Description                 |
| -------------------- | ------ | --------------------------- |
| `/v1/tomato/acquire` | POST   | Acquire a new tomato        |
| `/v1/tomato/slice`   | POST   | Slice tomatoes              |
| `/v1/tomato/squeeze` | POST   | Extract juice from tomatoes |

## Next Steps

* [Cooking Endpoints](/docs/core-modules/cooking-operations.md) - Simmer and roast your prepared ingredients
* [Pizza Endpoints](/docs/core-modules/pizza-creation-system.md) - Create and bake pizzas
* [Taste Endpoints](/docs/core-modules/taste-testing-module.md) - Analyze your finished dishes


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tomatopy.pizza/docs/core-modules/ingredient-manipulation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.