> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/fastapi/fastapi/llms.txt
> Use this file to discover all available pages before exploring further.
# Response
> Response classes for returning different types of HTTP responses in FastAPI
FastAPI provides several response classes for returning different types of content. These classes are built on top of Starlette's response classes and allow you to customize the response sent to the client.
## Importing
```python theme={null}
from fastapi.responses import (
Response,
JSONResponse,
HTMLResponse,
PlainTextResponse,
RedirectResponse,
StreamingResponse,
FileResponse,
EventSourceResponse,
)
```
## Response Classes
### `Response`
The base response class. Use this for custom responses or when you need full control.
**Constructor Parameters:**
The response body content.
HTTP status code.
HTTP headers.
Media type (Content-Type).
Background task to run after sending the response.
```python theme={null}
from fastapi import FastAPI
from fastapi.responses import Response
app = FastAPI()
@app.get("/custom")
async def custom_response():
return Response(
content="Custom content",
media_type="text/plain",
status_code=200,
headers={"X-Custom-Header": "value"},
)
```
**Attributes:**
The HTTP status code.
Response headers.
The response body.
The media type (Content-Type).
Background task to execute after response.
**Methods:**
* `set_cookie()` - Set a cookie
* `delete_cookie()` - Delete a cookie
### `JSONResponse`
Returns a JSON response. This is the default response class in FastAPI.
```python theme={null}
from fastapi import FastAPI
from fastapi.responses import JSONResponse
app = FastAPI()
@app.get("/items")
async def read_items():
return JSONResponse(
content={"items": ["item1", "item2"]},
status_code=200,
headers={"X-Custom-Header": "value"},
)
```
**Note:** When using `JSONResponse` directly, the content must be JSON-serializable. FastAPI's automatic response serialization using Pydantic models is often more convenient:
```python theme={null}
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
@app.get("/items", response_model=Item)
async def read_item():
return Item(name="Portal Gun", price=42.0)
```
### `HTMLResponse`
Returns an HTML response.
```python theme={null}
from fastapi import FastAPI
from fastapi.responses import HTMLResponse
app = FastAPI()
@app.get("/", response_class=HTMLResponse)
async def read_root():
html_content = """
My App
Hello World!
"""
return html_content
# Or return HTMLResponse directly:
@app.get("/page")
async def read_page():
return HTMLResponse(content="Hello
", status_code=200)
```
### `PlainTextResponse`
Returns a plain text response.
```python theme={null}
from fastapi import FastAPI
from fastapi.responses import PlainTextResponse
app = FastAPI()
@app.get("/text", response_class=PlainTextResponse)
async def read_text():
return "Hello, World!"
# Or return PlainTextResponse directly:
@app.get("/plain")
async def plain():
return PlainTextResponse("Plain text content")
```
### `RedirectResponse`
Returns an HTTP redirect response.
**Constructor Parameters:**
The URL to redirect to.
HTTP status code (307 for temporary redirect, 308 for permanent).
Additional headers.
```python theme={null}
from fastapi import FastAPI
from fastapi.responses import RedirectResponse
app = FastAPI()
@app.get("/old-path")
async def old_path():
return RedirectResponse(url="/new-path")
@app.get("/redirect")
async def redirect():
return RedirectResponse(
url="https://example.com",
status_code=302, # Temporary redirect
)
```
### `StreamingResponse`
Streams response content. Useful for large files, real-time data, or generated content.
**Constructor Parameters:**
An iterator or async iterator that yields bytes.
HTTP status code.
HTTP headers.
Media type (Content-Type).
```python theme={null}
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import asyncio
app = FastAPI()
@app.get("/stream")
async def stream():
async def generate():
for i in range(10):
yield f"data: {i}\n"
await asyncio.sleep(1)
return StreamingResponse(generate(), media_type="text/plain")
# Streaming a file:
@app.get("/video")
async def video():
def iterfile():
with open("video.mp4", "rb") as f:
yield from f
return StreamingResponse(iterfile(), media_type="video/mp4")
```
### `FileResponse`
Returns a file as the response. Automatically handles file streaming and sets appropriate headers.
**Constructor Parameters:**
Path to the file.
HTTP status code.
Additional headers.
Media type. If not set, it will be guessed from the file extension.
Filename for the Content-Disposition header.
```python theme={null}
from fastapi import FastAPI
from fastapi.responses import FileResponse
app = FastAPI()
@app.get("/download")
async def download_file():
return FileResponse(
path="report.pdf",
filename="monthly_report.pdf",
media_type="application/pdf",
)
@app.get("/image")
async def get_image():
return FileResponse("image.png")
```
### `EventSourceResponse`
Returns Server-Sent Events (SSE) for real-time streaming. This is FastAPI-specific and allows streaming events from async generators.
```python theme={null}
from fastapi import FastAPI
from fastapi.responses import EventSourceResponse
import asyncio
app = FastAPI()
@app.get("/events")
async def events():
async def generate():
for i in range(10):
yield {"event": "message", "data": f"Event {i}"}
await asyncio.sleep(1)
return EventSourceResponse(generate())
# With custom event types:
@app.get("/notifications")
async def notifications():
async def generate():
yield {"event": "start", "data": "Stream started"}
for i in range(5):
yield {
"event": "notification",
"data": f'{"message": "Update {i}"}',
"id": str(i),
}
await asyncio.sleep(2)
yield {"event": "end", "data": "Stream ended"}
return EventSourceResponse(generate())
```
## Using Response Classes
### Setting Default Response Class
You can set a default response class for the entire application or for specific routers:
```python theme={null}
from fastapi import FastAPI
from fastapi.responses import ORJSONResponse
# For the entire app:
app = FastAPI(default_response_class=ORJSONResponse)
# For a router:
from fastapi import APIRouter
router = APIRouter(default_response_class=HTMLResponse)
```
### Declaring Response Class in Path Operation
```python theme={null}
from fastapi import FastAPI
from fastapi.responses import HTMLResponse
app = FastAPI()
@app.get("/items", response_class=HTMLResponse)
async def read_items():
return "Items
"
```
### Returning Response Directly
```python theme={null}
from fastapi import FastAPI
from fastapi.responses import JSONResponse
app = FastAPI()
@app.get("/items")
async def read_items():
return JSONResponse(
content={"message": "Success"},
status_code=200,
headers={"X-Custom-Header": "value"},
)
```
## Setting Cookies
```python theme={null}
from fastapi import FastAPI
from fastapi.responses import JSONResponse
app = FastAPI()
@app.post("/login")
async def login():
response = JSONResponse(content={"message": "Logged in"})
response.set_cookie(
key="session_id",
value="abc123",
httponly=True,
max_age=3600,
secure=True,
samesite="lax",
)
return response
@app.post("/logout")
async def logout():
response = JSONResponse(content={"message": "Logged out"})
response.delete_cookie(key="session_id")
return response
```
## Custom Response Headers
```python theme={null}
from fastapi import FastAPI, Response
app = FastAPI()
@app.get("/items")
async def read_items(response: Response):
response.headers["X-Custom-Header"] = "Custom Value"
response.headers["X-Process-Time"] = "0.123"
return {"items": ["item1", "item2"]}
```
## Background Tasks
```python theme={null}
from fastapi import FastAPI, BackgroundTasks
from fastapi.responses import JSONResponse
app = FastAPI()
def write_log(message: str):
with open("log.txt", "a") as f:
f.write(message + "\n")
@app.post("/send-notification")
async def send_notification(background_tasks: BackgroundTasks):
background_tasks.add_task(write_log, "Notification sent")
return {"message": "Notification sent in background"}
# Or with Response:
@app.post("/process")
async def process():
response = JSONResponse(content={"status": "processing"})
response.background = BackgroundTask(write_log, "Processing started")
return response
```
## Common Response Patterns
### Success with Custom Status
```python theme={null}
@app.post("/items", status_code=201)
async def create_item(item: Item):
return item
```
### Error Response
```python theme={null}
from fastapi import HTTPException
@app.get("/items/{item_id}")
async def read_item(item_id: int):
if item_id not in items:
raise HTTPException(status_code=404, detail="Item not found")
return items[item_id]
```
### Custom Error Response
```python theme={null}
@app.get("/items/{item_id}")
async def read_item(item_id: int):
if item_id not in items:
return JSONResponse(
status_code=404,
content={"error": "Item not found", "item_id": item_id},
)
return items[item_id]
```