How do you receive a JSON request body?

Question

Accepted Answer

To receive a JSON request body in FastAPI, you declare a function parameter typed as a **Pydantic model**. FastAPI reads the body, parses the JSON, validates it against the model, and passes you a typed object — automatically.

## The pattern

```python
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    description: str | None = None      # optional field

@app.post("/items")
def create_item(item: Item):             # `item: Item` → read & validate the JSON body
    # `item` is a fully-validated Item object here
    return {"name": item.name, "total": item.price * 1.1}
```

```json
// request body the client sends:
{ "name": "Phone", "price": 999.0 }
```

Declaring `item: Item` tells FastAPI to read the request body as JSON, parse it into an `Item`, and **validate** it — your function receives a typed, valid object. Bad input is rejected automatically:

```json
// POST { "name": "Phone" }  (missing price) → automatic 422:
{ "detail": [{ "loc": ["body", "price"], "msg": "field required" }] }
```

## Body + path + query together

```python
@app.put("/items/{item_id}")
def update(item_id: int, item: Item, notify: bool = False):
    # item_id = path param, item = JSON body (Pydantic model), notify = query param
    # FastAPI distinguishes them by type/location automatically
```

FastAPI intelligently routes parameters: a path placeholder → path param, a Pydantic model → request body, a simple-typed parameter → query param.

## Multiple body parameters / partial updates

```python
@app.patch("/items/{id}")
def patch(id: int, item: ItemUpdate):       # use a model with all-optional fields for PATCH
    update_data = item.model_dump(exclude_unset=True)   # only fields the client sent
```

## Why it matters

Receiving and validating request bodies is essential — almost every API that creates or updates data needs it, and FastAPI makes it remarkably clean: declaring a Pydantic-model parameter gives you automatic JSON parsing, full **validation** (with clear field-level 422 errors), and a typed object, eliminating the tedious, error-prone manual parsing and validation other frameworks require.

The validation is also a key **security/robustness** benefit — malformed input is rejected before reaching your logic.

Understanding how to define a body model, how FastAPI distinguishes body from path/query parameters automatically, and patterns like `exclude_unset` for partial updates is fundamental everyday knowledge for building any write endpoint.