Skip to main content
The APIRouter class is used to group path operations together, typically for organizing an application into multiple files. It provides the same interface as FastAPI for defining routes but can be included in the main application or other routers.

​
Class Signature

from fastapi import APIRouter

router = APIRouter(
    prefix="",
    tags=None,
    dependencies=None,
    responses=None,
)

​
Constructor Parameters

​
prefix
str
default:""
An optional path prefix for the router. Must start with / and not end with /.
router = APIRouter(prefix="/api/v1")
​
tags
list[str | Enum] | None
default:"None"
A list of tags to be applied to all path operations in this router. It will be added to the generated OpenAPI.
router = APIRouter(tags=["users", "authentication"])
​
dependencies
Sequence[Depends] | None
default:"None"
A list of dependencies to be applied to all path operations in this router.
from fastapi import Depends

router = APIRouter(
    dependencies=[Depends(verify_token), Depends(verify_key)]
)
​
default_response_class
type[Response]
default:"JSONResponse"
The default response class to be used for all path operations in this router.
from fastapi.responses import ORJSONResponse

router = APIRouter(default_response_class=ORJSONResponse)
​
responses
dict[int | str, dict[str, Any]] | None
default:"None"
Additional responses to be shown in OpenAPI for all path operations in this router.
router = APIRouter(
    responses={
        404: {"description": "Not found"},
        500: {"description": "Internal server error"},
    }
)
​
callbacks
list[BaseRoute] | None
default:"None"
OpenAPI callbacks that should apply to all path operations in this router.
​
redirect_slashes
bool
default:"True"
Whether to detect and redirect slashes in URLs when the client doesn’t use the same format.
​
deprecated
bool | None
default:"None"
Mark all path operations in this router as deprecated in the generated OpenAPI.
router = APIRouter(deprecated=True)
​
include_in_schema
bool
default:"True"
Whether to include all path operations in this router in the generated OpenAPI.
router = APIRouter(include_in_schema=False)
​
lifespan
Lifespan[Any] | None
default:"None"
A Lifespan context manager handler for startup and shutdown events.
​
route_class
type[APIRoute]
default:"APIRoute"
Custom route class to be used by this router.
​
generate_unique_id_function
Callable[[APIRoute], str]
default:"generate_unique_id"
Customize the function used to generate unique IDs for path operations.
​
strict_content_type
bool
default:"True"
Enable strict checking for request Content-Type headers.

​
Methods

​
@router.get(path, **kwargs)

Define a GET endpoint.
@router.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

​
@router.post(path, **kwargs)

Define a POST endpoint.
@router.post("/items/")
async def create_item(item: Item):
    return item

​
@router.put(path, **kwargs)

Define a PUT endpoint.
@router.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.dict()}

​
@router.patch(path, **kwargs)

Define a PATCH endpoint.

​
@router.delete(path, **kwargs)

Define a DELETE endpoint.

​
@router.options(path, **kwargs)

Define an OPTIONS endpoint.

​
@router.head(path, **kwargs)

Define a HEAD endpoint.

​
@router.trace(path, **kwargs)

Define a TRACE endpoint.All decorators accept the same parameters as FastAPI path operation decorators:
​
response_model
Any
Pydantic model for response validation.
​
status_code
int | None
Default status code for the response.
​
tags
list[str | Enum] | None
Tags for OpenAPI documentation.
​
dependencies
Sequence[Depends] | None
Additional dependencies for this specific route.
​
summary
str | None
Short summary for OpenAPI documentation.
​
description
str | None
Detailed description for OpenAPI documentation.
​
deprecated
bool | None
Mark this route as deprecated.

​
add_api_route(path, endpoint, **kwargs)

Add an API route programmatically.
router.add_api_route(
    "/items/",
    read_items,
    methods=["GET"],
    tags=["items"],
)
Accepts the same parameters as the path operation decorators.

​
include_router(router, *, prefix="", tags=None, dependencies=None, **kwargs)

Include another APIRouter in this router.
​
router
APIRouter
required
The APIRouter to include.
​
prefix
str
default:""
URL path prefix for all routes in the included router.
​
tags
list[str | Enum] | None
Additional tags to be applied to all routes.
​
dependencies
Sequence[Depends] | None
Additional dependencies to be applied to all routes.
​
deprecated
bool | None
Mark all routes as deprecated.
​
include_in_schema
bool
default:"True"
Include routes in OpenAPI schema.
from fastapi import APIRouter

api_router = APIRouter()
users_router = APIRouter()

@users_router.get("/")
def read_users():
    return [{"name": "Rick"}, {"name": "Morty"}]

api_router.include_router(users_router, prefix="/users", tags=["users"])

​
add_api_websocket_route(path, endpoint, name=None, *, dependencies=None)

Add a WebSocket route programmatically.
​
path
str
required
WebSocket path.
​
endpoint
Callable
required
WebSocket endpoint function.
​
name
str | None
Name for the WebSocket route.
​
dependencies
Sequence[Depends] | None
Dependencies for this WebSocket route.
router.add_api_websocket_route("/ws", websocket_endpoint)

​
@router.websocket(path, name=None, *, dependencies=None)

Define a WebSocket endpoint.
from fastapi import APIRouter, WebSocket

router = APIRouter()

@router.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"Message: {data}")

​
Attributes

​
prefix
str
The path prefix for this router.
​
tags
list[str | Enum]
Tags applied to all routes in this router.
​
dependencies
list[Depends]
Dependencies applied to all routes in this router.
​
routes
list[BaseRoute]
List of all routes registered in this router.
​
deprecated
bool | None
Whether all routes are marked as deprecated.
​
include_in_schema
bool
Whether routes are included in the OpenAPI schema.

​
Example: Organizing Routes

# app/routers/users.py
from fastapi import APIRouter, Depends
from ..dependencies import get_token_header

router = APIRouter(
    prefix="/users",
    tags=["users"],
    dependencies=[Depends(get_token_header)],
    responses={404: {"description": "Not found"}},
)

@router.get("/")
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]

@router.get("/me")
async def read_user_me():
    return {"username": "current_user"}

@router.get("/{username}")
async def read_user(username: str):
    return {"username": username}

# app/routers/items.py
from fastapi import APIRouter

router = APIRouter(
    prefix="/items",
    tags=["items"],
    responses={404: {"description": "Not found"}},
)

@router.get("/")
async def read_items():
    return [{"name": "Portal Gun"}, {"name": "Plumbus"}]

@router.get("/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id, "name": "Portal Gun"}

# app/main.py
from fastapi import FastAPI
from .routers import users, items

app = FastAPI()

app.include_router(users.router)
app.include_router(items.router)

@app.get("/")
async def root():
    return {"message": "Hello World"}

​
Example: Nested Routers

from fastapi import APIRouter, FastAPI

app = FastAPI()

# Main API router
api_router = APIRouter(prefix="/api/v1")

# Sub-routers
users_router = APIRouter(prefix="/users", tags=["users"])
items_router = APIRouter(prefix="/items", tags=["items"])

@users_router.get("/")
def get_users():
    return [{"username": "user1"}]

@items_router.get("/")
def get_items():
    return [{"name": "item1"}]

# Include sub-routers in main router
api_router.include_router(users_router)
api_router.include_router(items_router)

# Include main router in app
app.include_router(api_router)

# URLs will be:
# /api/v1/users/
# /api/v1/items/

Build docs developers (and LLMs) love

Get started for freeTalk to us