> 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/readme-1/basic-concepts.md).

# Basic Concepts

Understanding the core concepts of the PizzaStack API will help you make the most of the platform. This guide introduces the fundamental ideas and components.

## Core Components

### 1. Sessions

Every interaction with PizzaStack happens within a session. A session is identified by the `X-Session-ID` header and groups all objects (tomatoes, sauces, bases, pizzas) together.

```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())  # One session per workflow
}
```

### 2. Ingredient Types

PizzaStack tracks ingredients through several states as they move through the pipeline:

* **Raw** -- freshly acquired tomatoes (`/tomato/acquire`)
* **Sliced** -- tomatoes that have been cut (`/tomato/slice`)
* **Juice** -- extracted liquid (`/tomato/squeeze`)
* **Sauce** -- cooked result (`/cook/simmer` or `/cook/roast`)

Each state has an ID you pass to subsequent endpoints.

```python
# Acquire a raw tomato
response = requests.post(f"{API_BASE}/tomato/acquire", headers=HEADERS, json={
    "variety": "San Marzano",
    "ripeness": 0.8,
    "weight": 150
})
tomato = response.json()
# tomato["id"] is a raw ingredient ID
```

### 3. The Pipeline

PizzaStack follows a defined pipeline for making pizza:

1. **Acquire** tomatoes via `/tomato/acquire`
2. **Prepare** them via `/tomato/slice` or `/tomato/squeeze`
3. **Cook** them via `/cook/simmer` or `/cook/roast`
4. **Create a base** via `/pizza/base`
5. **Assemble** everything via `/pizza/assemble`
6. **Bake** via `/pizza/bake`
7. **Analyze** via `/taste/analyze` or `/taste/compare`

## Key Concepts

### 1. Quality Propagation

Quality flows through the pipeline. The ripeness of your raw tomato affects the quality of your sliced tomato, which affects the quality of your sauce, which affects the final pizza score.

```python
# Higher ripeness leads to better sauce quality
response = requests.post(f"{API_BASE}/tomato/acquire", headers=HEADERS, json={
    "variety": "San Marzano",
    "ripeness": 0.95,  # High ripeness for best results
    "weight": 150
})
tomato = response.json()
print(tomato["type"])  # "raw"
```

### 2. Ingredient State Matters

Tomatoes must be sliced before they can be simmered into sauce. Passing raw tomato IDs directly to `/cook/simmer` will not return an error, but the resulting sauce quality will silently degrade.

```python
# CORRECT: slice first, then simmer
slice_resp = requests.post(f"{API_BASE}/tomato/slice", headers=HEADERS, json={
    "tomato_ids": [tomato["id"]],
    "method": "dice",
    "size": "medium",
    "consistency": "uniform"
})
sliced = slice_resp.json()

simmer_resp = requests.post(f"{API_BASE}/cook/simmer", headers=HEADERS, json={
    "ingredients": [{"id": sliced["id"], "name": "tomato", "amount": 150, "unit": "g"}],
    "temperature": 100,
    "duration": "30m"
})
sauce = simmer_resp.json()
print(sauce["sauce_quality"])  # "optimal"

# WRONG: raw tomato directly to simmer -- quality degrades silently
simmer_resp = requests.post(f"{API_BASE}/cook/simmer", headers=HEADERS, json={
    "ingredients": [{"id": tomato["id"], "name": "tomato", "amount": 150, "unit": "g"}],
    "temperature": 100,
    "duration": "30m"
})
bad_sauce = simmer_resp.json()
print(bad_sauce["sauce_quality"])  # "degraded"
```

### 3. Assembly Before Baking

Pizzas must be assembled via `/pizza/assemble` before they can be baked. Passing a bare `base_id` to `/pizza/bake` will return a `400` error.

```python
# You must assemble first to get a pizza_id
assemble_resp = requests.post(f"{API_BASE}/pizza/assemble", headers=HEADERS, json={
    "base_id": base["id"],
    "sauce_id": sauce["id"],
    "toppings": [{"name": "mozzarella", "amount": 200, "unit": "g"}]
})
pizza = assemble_resp.json()

# Then bake using the pizza_id
bake_resp = requests.post(f"{API_BASE}/pizza/bake", headers=HEADERS, json={
    "pizza_id": pizza["id"],
    "temperature": 450,
    "duration": "2m"
})
```

## Error Handling

The API returns standard HTTP status codes with JSON error bodies:

```python
response = requests.post(f"{API_BASE}/pizza/bake", headers=HEADERS, json={
    "pizza_id": "invalid_id",
    "temperature": 450,
    "duration": "2m"
})

if response.status_code != 200:
    error = response.json()
    print(f"Error {response.status_code}: {error['message']}")
```

## Best Practices

1. **Use One Session Per Workflow**

   Create a new session ID for each independent pizza-making workflow.
2. **Always Slice Before Cooking**

   ```python
   # Always slice tomatoes before passing to /cook/simmer
   slice_resp = requests.post(f"{API_BASE}/tomato/slice", headers=HEADERS, json={
       "tomato_ids": [tomato["id"]],
       "method": "dice",
       "size": "medium",
       "consistency": "uniform"
   })
   ```
3. **Check Response Status Codes**

   ```python
   response = requests.post(f"{API_BASE}/tomato/acquire", headers=HEADERS, json={...})
   response.raise_for_status()  # Raises an exception for 4xx/5xx
   data = response.json()
   ```

## Next Steps

* [Core API Endpoints](/docs/core-modules/ingredient-manipulation.md) - Dive deeper into specific endpoints
* [Tutorials](/docs/tutorials/making-your-first-marinara.md) - Follow step-by-step guides
* [Best Practices](/docs/best-practices.md) - Learn API usage patterns


---

# 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/readme-1/basic-concepts.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.