FastAPI Request Headers and Cookies

FastAPI providesHeaderandCookieType, used to get data from HTTP request headers and Cookies.

Request header parameter

UsageHeaderDeclare request header parameters:

Example

from typing import Annotated
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/items/")
async def read_items(
# Receive User-Agent request header
user_agent: Annotated[str | None, Header()] = None,
):
return {"User-Agent": user_agent}

Visithttp://127.0.0.1:8000/items/The returned JSON contains the browser's User-Agent information.

Automatic conversion of request headers

Field names in HTTP request headers use hyphens (e.g.,X-Token), while Python variable names cannot contain hyphens. FastAPI automatically performs the conversion:

Example

from typing import Annotated
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/items/")
async def read_items(
# Python variable names use underscores, FastAPI automatically converts to X-Token request header
x_token: Annotated[list[str] | None, Header()] = None,
):
return {"X-Token values": x_token}

Conversion rules:

Python variable names	HTTP request headers	Description
`x_token`	`X-Token`	Underscores automatically converted to hyphens
`user_agent`	`User-Agent`	Same as above
`content_type`	`Content-Type`	Same as above

FastAPI automatically converts underscores in variable names_Convert to hyphens-to match request headers. If you need to disable this conversion, setHeader(convert_underscores=False)。

Receiving duplicate request headers

Some request headers may appear multiple times (e.g.Set-Cookie), uselistType acceptance:

Example

from typing import Annotated
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/items/")
async def read_items(
# Receive multiple X-Token headers
x_token: Annotated[list[str] | None, Header()] = None,
):
return {"X-Token values": x_token}

Request example:

GET /items/ HTTP/1.1
X-Token: foo
X-Token: bar

Response:{"X-Token values": ["foo", "bar"]}

Cookie parameters

UsageCookieDeclare Cookie parameters:

Example

from typing import Annotated
from fastapi import FastAPI, Cookie

app = FastAPI()

@app.get("/items/")
async def read_items(
# Receive a cookie named session_token
session_token: Annotated[str | None, Cookie()] = None,
):
return {"session_token": session_token}

Using request headers and Cookies together

You can get both request headers and Cookies in the same route:

Example

from typing import Annotated
from fastapi import FastAPI, Header, Cookie

app = FastAPI()

@app.get("/items/")
async def read_items(
user_agent: Annotated[str | None, Header()] = None,
session_token: Annotated[str | None, Cookie()] = None,
ads_id: Annotated[str | None, Cookie()] = None,
):
return {
"User-Agent": user_agent,
"Session-Token": session_token,
"Ads-ID": ads_id,
}

Summary

UsageHeaderGet HTTP request header parameters
UsageCookieGet Cookie parameters
FastAPI automatically converts underscores in Python variable names to hyphens in request headers
Usagelist[str]Receiving duplicate request headers
Request header and Cookie parameters support the same validation rules as query parameters

other extensions