Path

API reference for the FastAPI Path parameter function

Path

Declare a path parameter for a path operation. Path parameters are always required and are extracted from the URL path.

from typing import Annotated
from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")],
):
    return {"item_id": item_id}

Signature

def Path(
    default: Any = ...,
    *,
    alias: str | None = None,
    title: str | None = None,
    description: str | None = None,
    gt: float | None = None,
    ge: float | None = None,
    lt: float | None = None,
    le: float | None = None,
    min_length: int | None = None,
    max_length: int | None = None,
    pattern: str | None = None,
    examples: list[Any] | None = None,
    deprecated: bool | str | None = None,
    include_in_schema: bool = True,
    json_schema_extra: dict[str, Any] | None = None,
) -> Any

Parameters

default · Any · default: "..."

Default value if the parameter field is not set. This doesn’t affect Path parameters as the value is always required. The parameter is available only for compatibility.

alias · str | None · default: "None"

An alternative name for the parameter field. This will be used to extract the data and for the generated OpenAPI. Particularly useful when you can’t use the name you want because it is a Python reserved keyword.

title · str | None · default: "None"

Human-readable title for the parameter.

description · str | None · default: "None"

Human-readable description for the parameter.

gt · float | None · default: "None"

Greater than validation. If set, the value must be greater than this. Only applicable to numbers.

ge · float | None · default: "None"

Greater than or equal validation. If set, the value must be greater than or equal to this. Only applicable to numbers.

lt · float | None · default: "None"

Less than validation. If set, the value must be less than this. Only applicable to numbers.

le · float | None · default: "None"

Less than or equal validation. If set, the value must be less than or equal to this. Only applicable to numbers.

min_length · int | None · default: "None"

Minimum length for strings.

max_length · int | None · default: "None"

Maximum length for strings.

pattern · str | None · default: "None"

RegEx pattern for strings.

discriminator · str | None · default: "None"

Parameter field name for discriminating the type in a tagged union.

strict · bool | None · default: "None"

If True, strict validation is applied to the field.

multiple_of · float | None · default: "None"

Value must be a multiple of this. Only applicable to numbers.

allow_inf_nan · bool | None · default: "None"

Allow inf, -inf, nan. Only applicable to numbers.

max_digits · int | None · default: "None"

Maximum number of allowed digits for numbers.

decimal_places · int | None · default: "None"

Maximum number of decimal places allowed for numbers.

examples · list[Any] | None · default: "None"

Example values for this field.

deprecated · bool | str | None · default: "None"

Mark this parameter field as deprecated. It will affect the generated OpenAPI (visible at /docs).

include_in_schema · bool · default: "True"

Whether to include this parameter field in the generated OpenAPI.

json_schema_extra · dict[str, Any] | None · default: "None"

Any additional JSON schema data.

Examples

Basic 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()]):
    return {"item_id": item_id}

Path Parameter with Metadata

@app.get("/items/{item_id}")
async def read_item(
    item_id: Annotated[int, Path(title="Item ID", description="The ID of the item to retrieve")]
):
    return {"item_id": item_id}

Numeric Validations

@app.get("/items/{item_id}")
async def read_item(
    item_id: Annotated[int, Path(gt=0, le=1000)]
):
    return {"item_id": item_id}

The item_id must be greater than 0 and less than or equal to 1000.

String Validations

@app.get("/users/{username}")
async def read_user(
    username: Annotated[str, Path(min_length=3, max_length=20, pattern="^[a-zA-Z0-9_]+$")]
):
    return {"username": username}

The username must be between 3 and 20 characters and can only contain alphanumeric characters and underscores.

Important Notes

Path parameters are always required. You cannot make them optional or provide default values.

Path parameters are extracted from the URL path template defined in the route decorator (e.g., /items/{item_id}).