fastapi/SKILL.md

---

name: fastapi description: FastAPI best practices and conventions. Use when working with FastAPI APIs, Pydantic models, dependencies, streaming responses including Server-Sent Events (SSE), and serving frontend apps. Keeps FastAPI code clean and up to date with the latest features and patterns.

---

BB Skills packaging and scoped native evidence (2026-10-07)

This is the official FastAPI skill from release 0.142.2, pinned to 78c4324f0c56bc5282a459978779a9e532d19709. All seven skill files match the official Python wheel byte for byte. The complete upstream MIT notice, copyright and six references are retained. Original instructions remain unchanged in upstream-original/SKILL.md; this marked preface and the examples are independent BB Skills additions, not upstream certification.

The local fixture executes ten native Python blocks plus independent synthetic contracts. Twenty-nine named observations passed with FastAPI 0.142.2, Pydantic 2.13.5, Starlette 1.7.0 and AnyIO 4.15.1 on Windows/Python 3.12.4. The primary transport is HTTPX2 2.13.1; a separate plain HTTPX 0.28.1 run is comparison evidence. Current Starlette documentation recommends HTTPX2 and deprecates plain HTTPX. The primary requirements do not install the older comparison client.

Observations cover Annotated path/query/body/list errors, normal public response projection, public schema fields, invalid returned data, dependency overrides and their cleanup, class-instance dependencies and yield lifetime relative to ASGI events. The original database-shaped snippet is supplied a synthetic session/query; no database connects. The native function-scope example's print call is captured as an event without rewriting the source. An independent direct-JSONResponse counterexample intentionally retains an extra field: a Response object bypasses declared response_model filtering. Do not deploy these teaching applications.

The original dependency endpoint returns a constant message, not the synthetic identity. The fixture observes provider calls rather than assuming a 200 response proves which provider ran. Response filtering, strict input fields and test overrides do not implement real identity, ownership or authorization.

The fixture makes 27 in-process TestClient HTTP requests per run. It forbids external socket connections and counts event-loop loopback sockets on Windows. No external API, real credential, cloud service, production data or paid model call is required. Dependency installation is separate and contacts the public registry. Python runtimes and wheels are not bundled. Frontend serving, telemetry export, streaming transport, production deployment, concurrent persistence and full security require separate verification.

This fixed download does not automatically follow master or future releases. Use the skill bundled with the FastAPI version your project installs when applying version-specific guidance. No complete AI-client skill execution occurred; runtime_tested remains false. Read examples/README.md and the two named evidence records for exact scope.

FastAPI

Official FastAPI skill to write code with best practices, keeping up to date with new versions and features.

Quick Reference

• Serve frontend apps: use app.frontend() or router.frontend() for built frontend assets; see Serve Frontend Apps.
• Server-Sent Events (SSE): use response_class=EventSourceResponse and yield; see Streaming and the streaming reference.
• JSON Lines and byte streaming: see the streaming reference.
• OpenTelemetry: use FastAPI's native traces, metrics, and logs. See OpenTelemetry.
• Dependencies: use Annotated[..., Depends(...)]; see Dependency Injection and the dependency injection reference for yield, scopes, and class dependencies.
• Response models: prefer return types; use response_model when the public response schema differs from the internal return value; see the response reference.
• Pydantic models: do not use ellipsis or RootModel; see the Pydantic reference.
• Routing: declare router-level prefix, tags, and shared dependencies on the APIRouter; see the path operation reference.
• Tooling and related libraries: use uv, Ruff, ty, Asyncer, SQLModel, and HTTPX when applicable; see the other tools reference.

Use the fastapi CLI

Run the development server on localhost with reload:

fastapi dev

Run the production server:

fastapi run

Prefer declaring the entrypoint in pyproject.toml:

[tool.fastapi]
entrypoint = "my_app.main:app"

When adding the entrypoint is not possible, or the user explicitly asks not to, pass the app file path:

fastapi dev my_app/main.py

Use Annotated

Always prefer the Annotated style for parameter and dependency declarations. It keeps function signatures working in other contexts, respects the types, and allows reusability.

Use Annotated for parameter declarations, including Path, Query, Header, etc.:

from typing import Annotated

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(
    item_id: Annotated[int, Path(ge=1, description="The item ID")],
    q: Annotated[str | None, Query(max_length=50)] = None,
):
    return {"message": "Hello World"}

Use Annotated for dependencies with Depends(). Unless asked not to, create a new type alias for the dependency to allow reusing it:

from typing import Annotated

from fastapi import Depends, FastAPI

app = FastAPI()


def get_current_user():
    return {"username": "johndoe"}


CurrentUserDep = Annotated[dict, Depends(get_current_user)]


@app.get("/items/")
async def read_item(current_user: CurrentUserDep):
    return {"message": "Hello World"}

Do not use Ellipsis for path operations or Pydantic models

Do not use ... as a default value for required parameters or model fields. It's not needed and not recommended.

from typing import Annotated

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float = Field(gt=0)


@app.post("/items/")
async def create_item(item: Item, project_id: Annotated[int, Query()]):
    return item

See the Pydantic reference for more details.

Return Type or Response Model

When possible, include a return type. It will be used to validate, filter, document, and serialize the response.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None


@app.get("/items/me")
async def get_item() -> Item:
    return Item(name="Plumbus", description="All-purpose home device")

Return types or response models filter data to avoid exposing sensitive information, and they let Pydantic serialize the data on the Rust side for performance.

Use response_model when the type you return is not the same as the public schema you want to validate, filter, document, and serialize. See the response reference.

Performance

Do not use ORJSONResponse or UJSONResponse, they are deprecated.

Instead, declare a return type or response model. Pydantic will handle the data serialization on the Rust side.

Including Routers

When declaring routers, prefer to add router-level parameters like prefix, tags, and shared dependencies to the router itself instead of in include_router().

from fastapi import APIRouter, Depends, FastAPI

app = FastAPI()


def get_current_user():
    return {"username": "johndoe"}


router = APIRouter(
    prefix="/items",
    tags=["items"],
    dependencies=[Depends(get_current_user)],
)


@router.get("/")
async def list_items():
    return []


app.include_router(router)

See the path operation reference for more routing patterns.

Serve Frontend Apps

Use app.frontend() to serve a built static frontend app, for example a directory generated by Vite, Astro, Angular, Svelte, Vue, or a similar tool.

from fastapi import FastAPI

app = FastAPI()

app.frontend("/", directory="dist")

Use router.frontend() when the frontend belongs to an APIRouter; normal router prefix behavior applies when the router is included.

from fastapi import APIRouter, FastAPI

app = FastAPI()
router = APIRouter(prefix="/admin")

router.frontend("/", directory="admin-dist")
app.include_router(router)

app.frontend() and router.frontend() are low-priority routes: regular API routes are matched first, then frontend files and client-side routing fallbacks. Use this for single-page apps and built frontend assets instead of mounting StaticFiles manually.

OpenTelemetry

Prefer FastAPI's native OpenTelemetry support for request traces, metrics, and logs.

Install fastapi[standard] to include the SDK and HTTP/protobuf exporters. Set OTEL_SERVICE_NAME to identify the app and OTEL_EXPORTER_OTLP_ENDPOINT to the collector's HTTP/protobuf base URL. Use OTEL_EXPORTER_OTLP_HEADERS when authentication is required.

Use FastAPI(telemetry={...}) for custom configuration, such as choosing signals or supplying providers.

See the OpenTelemetry tutorial for configuration details.

Dependency Injection

Use dependencies when the logic can't be declared in Pydantic validation, depends on external resources, needs cleanup with yield, or is shared across endpoints.

Apply shared dependencies at the router level via dependencies=[Depends(...)].

See the dependency injection reference for detailed patterns including yield with scope, and class dependencies.

Async vs Sync path operations

Use async path operations only when fully certain that the logic called inside is compatible with async and await, and that it doesn't block.

from fastapi import FastAPI

app = FastAPI()


@app.get("/async-items/")
async def read_async_items():
    data = await some_async_library.fetch_items()
    return data


@app.get("/items/")
def read_items():
    data = some_blocking_library.fetch_items()
    return data

In case of doubt, or by default, use regular def functions. They will be run in a threadpool so they don't block the event loop. The same rules apply to dependencies.

Make sure blocking code is not run inside of async functions. The logic will work, but will damage performance heavily.

When needing to mix blocking and async code, see Asyncer in the other tools reference.

Streaming (JSON Lines, SSE, bytes)

To stream Server-Sent Events, use response_class=EventSourceResponse and yield items from the endpoint.

from collections.abc import AsyncIterable

from fastapi import FastAPI
from fastapi.sse import EventSourceResponse, ServerSentEvent

app = FastAPI()


@app.get("/events", response_class=EventSourceResponse)
async def stream_events() -> AsyncIterable[ServerSentEvent]:
    yield ServerSentEvent(data={"status": "started"}, event="status", id="1")

Plain objects are automatically JSON-serialized as data: fields. Use ServerSentEvent for full control over SSE fields (event, id, retry, comment) and raw_data for pre-formatted strings.

See the streaming reference for JSON Lines, Server-Sent Events (EventSourceResponse, ServerSentEvent), and byte streaming (StreamingResponse) patterns.

Tooling

See the other tools reference for details on uv, Ruff, ty for package management, linting, type checking, formatting, etc.

Other Libraries

See the other tools reference for details on other libraries:

• Asyncer for handling async and await, concurrency, mixing async and blocking code, prefer it over AnyIO or asyncio.
• SQLModel for working with SQL databases, prefer it over SQLAlchemy.
• HTTPX for interacting with HTTP (other APIs), prefer it over Requests.

Do not use Pydantic RootModels

Do not use Pydantic RootModel; instead use regular type annotations with Annotated and Pydantic validation utilities.

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import Field

app = FastAPI()


@app.post("/items/")
async def create_items(items: Annotated[list[int], Field(min_length=1), Body()]):
    return items

FastAPI supports these type annotations and will create a Pydantic TypeAdapter for them, so types work normally without custom wrapper models. See the Pydantic reference.

Use one HTTP operation per function

Don't mix HTTP operations in a single function. Having one function per HTTP operation helps separate concerns and organize the code.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str


@app.get("/items/")
async def list_items():
    return []


@app.post("/items/")
async def create_item(item: Item):
    return item

See the path operation reference for more examples.