Header Parameters¶

You can define Header parameters the same way you defineQuery,Path andCookie parameters.

ImportHeader¶

First importHeader:

fromtypingimportAnnotatedfromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(user_agent:Annotated[str|None,Header()]=None):return{"User-Agent":user_agent}

fromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(user_agent:str|None=Header(default=None)):return{"User-Agent":user_agent}

DeclareHeader parameters¶

Then declare the header parameters using the same structure as withPath,Query andCookie.

You can define the default value as well as all the extra validation or annotation parameters:

fromtypingimportAnnotatedfromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(user_agent:Annotated[str|None,Header()]=None):return{"User-Agent":user_agent}

fromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(user_agent:str|None=Header(default=None)):return{"User-Agent":user_agent}

Automatic conversion¶

Header has a little extra functionality on top of whatPath,Query andCookie provide.

Most of the standard headers are separated by a "hyphen" character, also known as the "minus symbol" (-).

But a variable likeuser-agent is invalid in Python.

So, by default,Header will convert the parameter names characters from underscore (_) to hyphen (-) to extract and document the headers.

Also, HTTP headers are case-insensitive, so, you can declare them with standard Python style (also known as "snake_case").

So, you can useuser_agent as you normally would in Python code, instead of needing to capitalize the first letters asUser_Agent or something similar.

If for some reason you need to disable automatic conversion of underscores to hyphens, set the parameterconvert_underscores ofHeader toFalse:

fromtypingimportAnnotatedfromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(strange_header:Annotated[str|None,Header(convert_underscores=False)]=None,):return{"strange_header":strange_header}

fromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(strange_header:str|None=Header(default=None,convert_underscores=False),):return{"strange_header":strange_header}

Duplicate headers¶

It is possible to receive duplicate headers. That means, the same header with multiple values.

You can define those cases using a list in the type declaration.

You will receive all the values from the duplicate header as a Pythonlist.

For example, to declare a header ofX-Token that can appear more than once, you can write:

fromtypingimportAnnotatedfromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(x_token:Annotated[list[str]|None,Header()]=None):return{"X-Token values":x_token}

fromfastapiimportFastAPI,Headerapp=FastAPI()@app.get("/items/")asyncdefread_items(x_token:list[str]|None=Header(default=None)):return{"X-Token values":x_token}

If you communicate with thatpath operation sending two HTTP headers like:

X-Token: fooX-Token: bar

The response would be like:

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

Recap¶

Declare headers withHeader, using the same common pattern asQuery,Path andCookie.

And don't worry about underscores in your variables,FastAPI will take care of converting them.