# Response Models: Choosing What Goes Out

A response model says exactly which fields a route sends back, set by the route's return type or by response_model=, so separate models for what comes in and what goes out keep fields such as staff notes and password hashes inside the API.

Journeyman · FastAPI · Python · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Choose what a route sends back with a response model, set by its return type or response_model=
- Keep fields such as staff notes out of every answer with separate models for what comes in and what goes out

## Key takeaways

- A route that returns a stored dictionary sends every key in it, including fields the caller must never see.
- A response model lists the fields that may go out, and FastAPI drops every other key before it answers.
- The return type, such as -> ApplicationOut, sets the response model, and response_model= on the decorator does the same when the route returns a dictionary.
- An API keeps one model for what comes in and another for what goes out, because the two hold different fields.
- A request can't set a field its model doesn't have, so the status and staff notes stay the API's to decide.

The data behind an API nearly always holds things the caller mustn't see: a user's password hash, a store's cost price, a support team's notes about a customer. Whatever a route returns, the caller gets, so every route that reads stored data has to choose what leaves. This lesson makes that choice once, in a model, for Happy Tails.

## Everything you return goes out

Happy Tails stores each application with two things the applicant didn't send: its `status`, and the staff's private `staff_notes`. A route that finds an application and returns it, as *When It Isn't There: HTTPException and 404* found a game, looks harmless:

```python
@app.get("/applications/{application_id}")
def get_application(application_id: int):
    for application in APPLICATIONS:
        if application["id"] == application_id:
            return application
    raise HTTPException(status_code=404, detail=f"There's no application {application_id}.")
```

Theo checks on his application, and `GET /applications/2` answers 200 OK with everything:

```json
{"id":2,"name":"Theo","email":"theo@example.com","age":27,"pet_name":"Pepper","pet_type":"cat","has_yard":false,"status":"received","staff_notes":"Third-floor apartment. Check the lease allows cats."}
```

Theo can now read what the staff think of his apartment. A first fix deletes the key before returning: `application.pop("staff_notes")`. That deletes the notes from the stored data too, so staff lose them. Copying every other field into a new dictionary works, in this route; but every route that returns applications needs the same copy, and when someone stores a new private field next year, every route that forgot to leave it out sends it. A list of what may go out is safer than a list of what must stay in.

## A response model lists what goes out

That list is a model. `ApplicationOut` names the fields the applicant may see, and the route's return type names the model:

```python
class ApplicationOut(BaseModel):
    id: int
    name: str
    pet_name: str
    pet_type: str
    status: str


@app.get("/applications/{application_id}")
def get_application(application_id: int) -> ApplicationOut:
    for application in APPLICATIONS:
        if application["id"] == application_id:
            return application
    raise HTTPException(status_code=404, detail=f"There's no application {application_id}.")
```

`-> ApplicationOut` is read "returns an ApplicationOut". FastAPI takes whatever the route returns, builds an `ApplicationOut` from it, and sends only that model's fields. The same request now answers:

```json
{"id":2,"name":"Theo","pet_name":"Pepper","pet_type":"cat","status":"received"}
```

The notes stay on the server, and so do the email and age, which this page doesn't need. A field stored next year stays in too, until someone adds it to `ApplicationOut` on purpose. A model used this way is a **response model**.

## response_model= and lists

The route above returns a dictionary while its return type says `ApplicationOut`, a small fib that a type checker such as mypy, which Module 5 sets up, points out. `response_model=` on the decorator says the same thing, and the function's return type can then stay off (when a route has both, `response_model=` wins):

```python
@app.get("/applications", response_model=list[ApplicationOut])
def list_applications():
    return APPLICATIONS
```

`list[ApplicationOut]` filters every item in the list, so staff notes leave no application:

```json
[{"id":1,"name":"Maya","pet_name":"Biscuit","pet_type":"dog","status":"approved"},{"id":2,"name":"Theo","pet_name":"Pepper","pet_type":"cat","status":"received"}]
```

It works one way only: a response model can drop extra keys, but it can't invent missing ones. If a route returns a dictionary without `status`, FastAPI can't build the model and answers 500 Internal Server Error. That's the code's mistake, not the caller's, so you'll find it in your tests, not in a 422.

## One model in, one model out

What comes in and what goes out are different lists of fields. The applicant sends their details but never an id, a status or notes; the answer has an id and a status but never the notes. So an API keeps two models:

```python
@app.post("/applications", status_code=201, response_model=ApplicationOut)
def apply(application: ApplicationIn):
    saved = {"id": len(APPLICATIONS) + 1, **application.model_dump(), "status": "received", "staff_notes": ""}
    APPLICATIONS.append(saved)
    return saved
```

`ApplicationIn` is the `Application` model from *Field Rules: Lengths, Ranges and Choices*, renamed, with every rule. Its missing fields protect the API too. Rosa tries `"status": "approved"` and `"staff_notes": "Approve at once!"` in her body; `ApplicationIn` has neither field, so both are dropped, and the answer is 201 Created with the status the route set:

```json
{"id":3,"name":"Rosa","pet_name":"Clover","pet_type":"rabbit","status":"received"}
```

A request that sets fields it shouldn't, such as its own status or an `is_admin` flag, is called **mass assignment**, and separate models are the first defense against it. The docs page lists both models under **Schemas**, so the people who build the website see exactly what to send and what they'll get back:

![FastAPI's docs page for the Happy Tails API, scrolled to Schemas, with ApplicationIn opened to show name, email, age, pet_name, pet_type, has_yard and phone, and ApplicationOut opened to show id, name, pet_name, pet_type and status](https://www.ask-codey.com/lessons/TODO)

## Check yourself

2 questions to try on the lesson page.

## So what

A response model turns "be careful in every route" into one list of what may leave, written once, so private fields stay private even in routes written next year by someone else.

## Key terms

- [Response Model](https://www.ask-codey.com/glossary/response-model)
- [BaseModel](https://www.ask-codey.com/glossary/basemodel)
- [Mass Assignment](https://www.ask-codey.com/glossary/mass-assignment)

## Related

- [Request Models with Pydantic](https://www.ask-codey.com/lessons/fastapi-pydantic-request-models)
- [Field Rules: Lengths, Ranges and Choices](https://www.ask-codey.com/lessons/fastapi-pydantic-field-rules)
- [When It Isn't There: HTTPException and 404](https://www.ask-codey.com/lessons/fastapi-not-found-httpexception)

Source: https://www.ask-codey.com/lessons/fastapi-pydantic-response-models
