Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 50 ยท Request parameters

Path parameters

Capture values from the URL with typed FastAPI path parameters. See automatic conversion, 422 errors, Enum choices, file-path converters and route order.

Many URLs contain a value: /users/42, /books/dune, /files/reports/2026/q1.csv. In FastAPI you capture such a value by putting its name in braces inside the path, and declaring a function parameter with the same name. The type hint on that parameter tells FastAPI how to convert and validate the text that arrives in the URL.

Path parameters identify which resource a request is about. They are always required, because the URL cannot match without them. Optional extras belong in query parameters, which the next lesson covers.

Declaring a path parameter

Write the name in braces in the path, and add a parameter with that exact name to the function:

Python
@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

A URL is just text, so /users/42 delivers the string "42". Because you wrote int, FastAPI converts it before calling your function. Inside the function, user_id really is the integer 42.

Python Typed path parameters

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Two things to notice. First, you can have several path parameters in one path. Second, "007" converts to the integer 7, because the conversion follows Python's int().

Automatic validation and 422 errors

What if the text cannot be converted? Try it. The request never reaches your function, and the client gets status 422 Unprocessable Content with a precise description:

Python What a bad value looks like

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The detail list has one entry per problem. Each entry holds a machine-readable type, a loc that says where the problem was (["path", "user_id"]), a human-readable msg and the offending input. Clients can show these messages next to the right form field. The same shape is used for every kind of input error, so you will see it again with query strings and request bodies.

Common path types:

Hint Accepts Example
str any text without / dune
int whole numbers 42
float decimals 3.14
bool true, false, 1, 0 and similar true
UUID a UUID string 550e8400-e29b-41d4-a716-446655440000
date ISO date 2026-03-01

Other types such as datetime and Decimal work the same way.

Choosing from fixed values with Enum

When only certain values make sense, declare an Enum. FastAPI accepts exactly the listed values and rejects everything else, and the documentation lists the choices.

Python Enum path parameters

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Inside the function, size is a real Size member, so comparing with Size.large is safe and typo-proof. Inheriting from str as well as Enum makes the members behave like strings, which keeps JSON conversion simple. The 422 response lists the allowed values in its message.

Paths that contain slashes

A normal str parameter stops at the next /. To capture something like reports/2026/q1.csv in one parameter, use Starlette's path converter by adding :path after the name:

Python The :path converter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The converter has no effect on the type hint; the value is still a str. Put a :path parameter at the end of a route, because it swallows everything after it.

Never open the path you receive without checking it. A client could send ../../etc/passwd. If you really serve files, resolve the path and verify it stays inside your allowed folder, or use a framework feature built for it.

Route order matters

FastAPI checks routes in the order you declare them and uses the first match. That matters when a fixed path and a parameterized path overlap. Here, /users/me should return the current user, but /users/{user_id} can also match it:

Python Route order pitfall

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In the second app, /users/me is tried against /users/{user_id} first. "me" is not an integer, so the request fails with 422 and never reaches the route that was meant for it. The fix is simple: declare specific paths before general ones.

Documenting parameters

You can add validation and documentation to a path parameter with Path(). For example, a number that must be positive:

Python
from typing import Annotated
from fastapi import FastAPI, Path

@app.get("/items/{item_id}")
async def read_item(
    item_id: Annotated[int, Path(gt=0, description="Database id of the item")],
):
    return {"item_id": item_id}

Path() takes the same constraints you will meet with Query() in the next lesson: gt, ge, lt, le for numbers, and min_length, max_length and pattern for text. A request for /items/0 is then rejected with a 422 that says the value must be greater than 0.

Use Annotated. Modern FastAPI recommends putting extra metadata inside Annotated[type, Path(...)] rather than as a default value. The function signature then stays a normal Python signature that works outside FastAPI too.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A route is /items/{item_id} and the function declares item_id: int. What does /items/abc produce?

    FastAPI cannot convert abc to int, so validation fails before your function runs. The client receives 422 with the location path/item_id.
  2. 2. Why should /users/me be declared before /users/{user_id}?

    The first matching route wins. If the parameterized route comes first, it tries to convert me to an int and fails, and the fixed route is never reached.
  3. 3. How do you capture a value that can contain slashes, such as docs/a/b.txt?

    The :path converter matches the rest of the URL including slashes. The parameter is still a str.
  4. 4. What is the benefit of declaring a path parameter as an Enum?

    An Enum restricts the parameter to its members. Any other value gets a 422 error, and the generated documentation lists the options.

Summary

  • Put in the path and declare a function parameter with the same name.
  • The type hint converts the text from the URL; failures give a 422 with loc, msg and input.
  • Use Enum for fixed choices and {name:path} to capture slashes.
  • Routes match in declaration order: put specific paths before general ones.
  • Annotated[int, Path(gt=0)] adds constraints and documentation.

Next, handle optional filters and paging with Query parameters.