> For the complete documentation index, see [llms.txt](https://tomatopy.pizza/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tomatopy.pizza/docs/tutorials/making-your-first-marinara.md).

# Making Your First Sauce

This tutorial walks you through creating a classic marinara sauce using the PizzaStack HTTP API. You will acquire tomatoes, slice them, and simmer them into a sauce.

## Prerequisites

Before starting, make sure you have:

* A PizzaStack API key (sign up at [tomatopy.pizza](https://tomatopy.pizza))
* Python with the `requests` library installed (`pip install requests`)

## Setup

First, set up your HTTP client and session:

```python
import requests
import uuid

API_BASE = "https://api.tomatopy.pizza/v1"
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key",
    "X-Session-ID": str(uuid.uuid4())
}
```

## Step 1: Acquire Tomatoes

Let's acquire some high-quality San Marzano tomatoes:

```python
# Acquire tomatoes
response = requests.post(f"{API_BASE}/tomato/acquire", headers=HEADERS, json={
    "variety": "San Marzano",
    "ripeness": 0.9,
    "weight": 800
})
response.raise_for_status()
tomato = response.json()

print(f"Acquired: {tomato['variety']} (type: {tomato['type']})")
# Acquired: San Marzano (type: raw)
```

## Step 2: Slice the Tomatoes

Tomatoes must be sliced before simmering. Skipping this step will silently degrade your sauce quality.

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

print(f"Sliced into {sliced['piece_count']} pieces")
```

## Step 3: Simmer Into Sauce

Now simmer the sliced tomatoes with garlic and basil:

```python
# Simmer into sauce
response = requests.post(f"{API_BASE}/cook/simmer", headers=HEADERS, json={
    "ingredients": [
        {"id": sliced["id"], "name": "tomato", "amount": 800, "unit": "g"}
    ],
    "temperature": 100,
    "duration": "45m"
})
response.raise_for_status()
sauce = response.json()

print(f"Sauce ID: {sauce['id']}")
print(f"Consistency: {sauce['consistency']}")
print(f"Sauce Quality: {sauce['sauce_quality']}")
```

## Step 4: Taste Test the Sauce

Analyze the sauce to check its flavor profile:

```python
# Analyze the sauce
response = requests.post(f"{API_BASE}/taste/analyze", headers=HEADERS, json={
    "dish_id": sauce["id"],
    "depth": "comprehensive",
    "include_aroma": True,
    "include_texture": True
})
response.raise_for_status()
profile = response.json()

print(f"Sweetness: {profile['sweetness']}")
print(f"Acidity: {profile['acidity']}")
print(f"Umami: {profile['umami']}")
print(f"Aroma intensity: {profile['aroma']['intensity']}")
print(f"Texture score: {profile['texture']['score']}")
```

## Complete Script

Here is the full script in one piece:

```python
import requests
import uuid

API_BASE = "https://api.tomatopy.pizza/v1"
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key",
    "X-Session-ID": str(uuid.uuid4())
}

# Step 1: Acquire tomatoes
tomato = requests.post(f"{API_BASE}/tomato/acquire", headers=HEADERS, json={
    "variety": "San Marzano",
    "ripeness": 0.9,
    "weight": 800
}).json()
print(f"1. Acquired {tomato['variety']} tomato (type: {tomato['type']})")

# Step 2: Slice the tomatoes
sliced = requests.post(f"{API_BASE}/tomato/slice", headers=HEADERS, json={
    "tomato_ids": [tomato["id"]],
    "method": "dice",
    "size": "medium",
    "consistency": "uniform"
}).json()
print(f"2. Sliced into {sliced['piece_count']} pieces")

# Step 3: Simmer into sauce
sauce = requests.post(f"{API_BASE}/cook/simmer", headers=HEADERS, json={
    "ingredients": [
        {"id": sliced["id"], "name": "tomato", "amount": 800, "unit": "g"}
    ],
    "temperature": 100,
    "duration": "45m"
}).json()
print(f"3. Sauce ready (sauce_quality: {sauce['sauce_quality']})")

# Step 4: Analyze
profile = requests.post(f"{API_BASE}/taste/analyze", headers=HEADERS, json={
    "dish_id": sauce["id"],
    "depth": "comprehensive",
    "include_aroma": True,
    "include_texture": True
}).json()
print(f"4. Flavor profile: sweetness={profile['sweetness']}, "
      f"acidity={profile['acidity']}, umami={profile['umami']}")
```

## Troubleshooting

### Common Issues

1. **Low Quality Sauce**

   Did you slice the tomatoes first? Passing raw tomato IDs to `/cook/simmer` will silently degrade quality. Always call `/tomato/slice` before `/cook/simmer`.
2. **401 Unauthorized**

   Check that your `X-API-Key` header is set correctly.
3. **400 Bad Request**

   Make sure all required fields are present in your JSON body. Check the error message in the response for details.

## Next Steps

* [Perfect Pizza Production](/docs/tutorials/perfect-pizza-production.md) - Use your sauce to make a complete pizza
* [Advanced Flavor Profiling](/docs/tutorials/advanced-flavor-profiling.md) - Deep dive into taste analysis
* [API Usage Best Practices](/docs/best-practices/code-efficiency.md) - Tips for efficient API usage


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://tomatopy.pizza/docs/tutorials/making-your-first-marinara.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.