What is the :path converter in FastAPI?

What's really being asked

This question probes whether you understand the layer beneath FastAPI's type hints, specifically Starlette's path conversion and URL routing semantics. It separates candidates who treat path parameters as simple string injection from those who know how the router segments URLs on slash boundaries.

The full answer

First, the default behavior of a standard str parameter. In FastAPI, declaring file_path as str in a route like /files/{file_path} tells the router to match one path segment. The str type hint controls Pydantic validation and documentation, but the router still stops at the next forward slash. Second, the behavior of the path converter. Adding :path inside the curly braces, as in {file_path:path}, instructs Starlette's router to use the path converter, which greedily consumes the rest of the URL including slashes. Third, the exact scenario where this is necessary. You need :path when the parameter itself represents a nested filesystem route or any value that legitimately contains slashes, such as /files/docs/tutorial.md. Without the converter, docs and tutorial.md would be treated as separate segments and the route would fail to match. Fourth, the architectural distinction. The candidate should note that :path is a Starlette path converter, not a Pydantic type, and that it operates at the routing layer before Pydantic validation ever sees the value.

The mistakes people make

Claiming that a plain str type hint automatically allows slashes inside the parameter. Saying that :path is a Pydantic validator or a Python type annotation rather than a router directive. Suggesting the solution is to use query parameters without first explaining why the path parameter approach fails. Asserting that URL-encoded slashes allow a str parameter to work, which misses the point that the router still segments on decoded slashes.

What usually comes next

How would you prevent path traversal attacks when using :path to serve files? What other Starlette path converters exist, such as int or float, and how do they affect the generated OpenAPI schema? How does FastAPI document a path converter in the automatic docs? What happens if you combine :path with a trailing slash in the route definition?

A concrete example

If you define app.get("/files/{file_path}") and request /files/docs/tutorial.md, the router sees three segments after the prefix and returns a 404 because only one segment was expected. If you change the route to /files/{file_path:path}, the same request matches, and file_path receives the string docs/tutorial.md, allowing you to serve nested content.