Parameters

Purpose

The "Param" family is how FastAPI knows whether a function argument should come from the path, the query string, headers, cookies, body, form data, or a file. Two files together define this surface:

• fastapi/params.py — class hierarchy of pydantic.FieldInfo subclasses.
• fastapi/param_functions.py — functional wrappers (Path(...), Query(...), Header(...), Cookie(...), Body(...), Form(...), File(...), Depends(...), Security(...)).

The functional wrappers are the names users import. Each calls into the corresponding class with the right defaults.

Key abstractions

Symbol (in fastapi/params.py)	Purpose
ParamTypes	Enum of query, header, path, cookie.
Param	Base subclass of pydantic.FieldInfo. Carries in_: ParamTypes and include_in_schema.
Path, Query, Header, Cookie	Concrete Param subclasses. Header adds convert_underscores (translates user_agent → user-agent).
Body	FieldInfo subclass for JSON bodies. Carries media_type, embed, examples.
Form, File	Body subclasses with media types application/x-www-form-urlencoded and multipart/form-data. File ties into UploadFile.
Depends	Dataclass holding a callable plus use_cache: bool and scope. Recognised by the dependency resolver.
Security	Depends subclass that additionally carries scopes: Sequence[str] for OAuth2.

The functional wrappers in fastapi/param_functions.py accept the same long parameter list (alias options, validation constraints, examples, deprecation flags, OpenAPI metadata, etc.) and return an instance of the appropriate class. The wrappers exist so that user code reads as Annotated[str, Query(min_length=3)] rather than Annotated[str, params.Query(min_length=3)].

How it works

graph LR
    User["param: Annotated[str, Query(min_length=3)] = 'x'"]
    User --> Sig[Function signature inspection]
    Sig --> GetDep["get_dependant(call=endpoint)"]
    GetDep --> Analyze[Walk parameters, classify by FieldInfo subclass]
    Analyze --> Dependant["Dependant.path_params / .query_params / .header_params / .cookie_params / .body_params / .dependencies"]
    Dependant --> Solve["solve_dependencies"]
    Solve --> Validate["Pydantic ModelField.validate"]
    Validate --> Endpoint

The classification logic lives in analyze_param and surrounding code in fastapi/dependencies/utils.py. It walks each function parameter and decides:

1. Is the metadata a Param / Body / Form / File? Use that.
2. Is the metadata a Depends / Security? Add it as a sub-dependency.
3. Is the parameter name in the path? Treat as Path.
4. Is it a Pydantic model annotation? Treat as Body (or Query if the model is configured for query params).
5. Otherwise treat as Query.

Each parameter becomes a ModelField (fastapi/_compat/v2.py), and the pile is grouped onto the route's Dependant. At request time solve_dependencies (fastapi/dependencies/utils.py) reads the request, applies validation, and produces kwargs for the endpoint.

Notable behaviours

• Annotated is the recommended style since FastAPI ≥0.95. The function default is the runtime default; metadata describes the parameter. Old-style defaults (def f(name: str = Query(default="x"))) still work and are extensively tested.
• Header underscore conversion. When convert_underscores=True (default), user_agent: str reads from the User-Agent header. Set convert_underscores=False to opt out.
• Form and File require python-multipart to be installed. fastapi/dependencies/utils.py:ensure_multipart_is_installed raises a clear error if it is missing or if the wrong multipart package is installed instead.
• regex= is deprecated — use pattern=. The deprecated alias is plumbed through with a typing_extensions.deprecated marker that fires FastAPIDeprecationWarning.
• Depends() with no callable infers the callable from the parameter's type annotation. So db: Annotated[Database, Depends()] is shorthand for Depends(Database).

Integration points

• Read by fastapi/dependencies/utils.py:get_dependant to build the Dependant tree.
• Read by fastapi/openapi/utils.py:_get_openapi_operation_parameters (and related helpers) to populate the OpenAPI parameters and request body.
• Used directly by user code through fastapi/__init__.py re-exports of the function wrappers.

Entry points for modification

• New parameter location: extend ParamTypes and add a class in fastapi/params.py, a wrapper in fastapi/param_functions.py, classification in fastapi/dependencies/utils.py:analyze_param, and OpenAPI plumbing in fastapi/openapi/utils.py.
• New validation option: add it to Param.__init__ (or Body.__init__), plumb it into the function wrappers in fastapi/param_functions.py, and forward to pydantic.fields.FieldInfo.
• Deprecation: wrap the parameter with typing_extensions.deprecated(...) in the function wrapper signature, raise FastAPIDeprecationWarning when used.