> 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://tomatopy.pizza/docs/readme-1/basic-concepts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.