Validate IDs and numeric segments
Constrain numeric identifiers captured in a route.
FastAPI · Function
Path
Path declares a URL path parameter for a FastAPI path operation. It provides schema metadata and validation while the parameter remains required because it is part of the route.
How it works
Path creates a declaration for a path-operation parameter. FastAPI uses its type annotation to parse the URL value and uses Path options to add metadata and validation; because the value is part of the route, it remains required regardless of defaults.
Syntax
Path(default=..., *, default_factory=_Unset, alias=None, alias_priority=_Unset, validation_alias=None, serialization_alias=None, 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 declared default; it does not make a Path parameter optional. |
default_factory | Callable[[], Any] | None | Callable used to generate a default; it does not affect Path requiredness. |
alias | str | None | Alternative external name for the parameter. |
title | str | None | Human-readable schema title. |
description | str | None | Description for the generated schema. |
ge | annotated numeric value | None | Inclusive minimum numeric bound. |
gt | annotated numeric value | None | Exclusive minimum numeric bound. |
le | annotated numeric value | None | Inclusive maximum numeric bound. |
lt | annotated numeric value | None | Exclusive maximum numeric bound. |
min_length | int | None | Minimum string length. |
max_length | int | None | Maximum string length. |
pattern | str | None | Regular-expression pattern constraint. |
Returns
A path-parameter declaration used in a path-operation function or dependency.
Key points
- Use Path in a path-operation function parameter to declare that the value comes from the URL path.
- Path accepts metadata and validation controls similar to Query, including descriptions and numeric bounds.
- A ge constraint sets an inclusive lower bound for numeric path values.
- The numeric validation options are not limited to integer annotations; they also apply to floats.
- The default and default_factory arguments exist for compatibility, but they do not alter path-parameter requiredness.
Common mistakes
- A default value or default factory does not make a Path parameter optional; the route still requires it.
- Declaring None or a default does not change the required nature of a path parameter.
Example: Validated path parameter
from typing import Annotated
from fastapi import FastAPI, Path
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(
item_id: Annotated[int, Path(title="The ID of the item to get", ge=1)],
):
return {"item_id": item_id}
The route captures item_id, while Path adds metadata and requires the integer to be at least 1.
When to use it
Document route parameters
Add titles or descriptions to generated OpenAPI parameter schemas.
Validate textual segments
Enforce string length or pattern rules on path segments.
Interview questions
QWhat does Path do in FastAPI?
Path declares metadata and validation for a parameter captured from the URL path. The parameter's Python annotation controls its converted type, while options such as ge constrain accepted values.
Follow-up: How would you make the captured value an integer no smaller than 1? Use an int annotation together with Path(ge=1), preferably through Annotated.
QCan a Path parameter be optional?
Path parameters are required because they must match a placeholder in the route. Supplying a default or None does not make the placeholder optional.
Follow-up: How should an optional filter be represented instead? Put it in a query parameter, such as Query(default=None), rather than in the route path.
QWhich kinds of constraints can Path express?
Path supports validation and metadata comparable to Query, including numeric constraints such as ge, le, gt, and lt. These constraints are applied to the converted path value and included in the generated API schema.
Follow-up: What happens when ge=1 is applied to a float parameter? FastAPI validates the float against the same lower-bound rule.
Related
QueryBodyCookieHeaderAnnotatedFastAPI