Inspect request headers
Read client metadata such as User-Agent from incoming requests.
FastAPI · Function
Header
Header declares an HTTP request-header parameter for a FastAPI path operation or dependency. It supports defaults, validation, metadata, aliases, and automatic underscore-to-hyphen conversion.
How it works
Header creates a request-parameter declaration for extracting and documenting an HTTP header in a path operation or dependency. FastAPI maps underscores in the Python parameter name to hyphens in the header name by default, while validation and metadata options configure the accepted value and generated schema.
Syntax
Header(default=Undefined, *, default_factory=_Unset, alias=None, alias_priority=_Unset, validation_alias=None, serialization_alias=None, convert_underscores=True, title=None, description=None, gt=None, ge=None, lt=None, le=None, min_length=None, max_length=None, pattern=None, regex=None, discriminator=None, strict=_Unset, multiple_of=_Unset, allow_inf_nan=_Unset, max_digits=None, decimal_places=None, examples=None, example=_Unset, openapi_examples=None, deprecated=None, include_in_schema=True, json_schema_extra=None, **extra)Parameters
| Name | Type | Description |
|---|---|---|
default | Any | The default value used when the parameter field is not set. |
default_factory | Callable[[], Any] | None | A callable that generates the default value. |
alias | str | None | An alternate external name for the parameter. |
convert_underscores | bool | Whether underscores in the Python name are converted to hyphens. |
**extra | Any | Validation, schema, and documentation options accepted by the request parameter declaration. |
Returns
Any
Key points
- Use Header in a path-operation parameter or dependency, commonly wrapped with
Annotated. - Import it directly with
from fastapi import Header. - Header belongs to the same request-parameter family as Path, Query, and Cookie.
- Its shared parameter behavior comes from the common Param base class.
- Header names are case-insensitive, so Python snake_case is appropriate for declarations.
- Set convert_underscores=False when the external header must retain underscores.
Common mistakes
- Using an ordinary function parameter makes FastAPI treat it as a query parameter rather than a request header.
- A Python name such as
user_agentnormally targets theuser-agentheader; disable this mapping withconvert_underscores=Falsewhen required.
Example: Read a request header
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
return {"User-Agent": user_agent}
Declares an optional request header and returns its value.
When to use it
Authenticate or authorize requests
Require or validate tokens and custom client headers.
Describe the API contract
Publish header requirements and constraints in generated OpenAPI documentation.
Interview questions
QWhat does FastAPI Header do?
Header declares a path-operation or dependency parameter whose value comes from an HTTP request header. It also supplies validation and OpenAPI metadata through the common parameter options.
Follow-up: How does a snake_case Python name become an HTTP header name? By default, FastAPI converts underscores to hyphens; set convert_underscores=False to preserve underscores.
QHow do you make a header optional or required?
The default is Undefined, so a header can be required when no default or optional type/default is supplied. A default value or None makes the declaration optional according to the annotation and default.
Follow-up: What happens if Header is omitted entirely? FastAPI interprets the parameter as a query parameter, not a header.
QWhich Header options commonly matter?
The function exposes convert_underscores=True by default, along with options such as alias, length and numeric constraints, regular-expression patterns, examples, deprecation, and schema inclusion. These configure extraction, validation, and documentation.
Follow-up: When would alias be useful? Use it when the external header name should differ from the Python parameter name or automatic underscore conversion.
Related
QueryPathCookieParamAnnotated