FastAPI
Python API with typed request validation and generated OpenAPI docs.
The rule
This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.
Types are the contract
- Every request body is a Pydantic model. Never `dict` or `Any` — that throws away validation, documentation and type safety at once.
- Every endpoint declares a response model, or internal fields leak to clients.
- Annotate return types. They are checked and documented.
Async
- No blocking I/O inside
async def. A synchronous driver orrequestscall stalls the event loop for every other request. - If a library is synchronous, declare the handler
defand let FastAPI use a threadpool.
Configuration
- One
Settingsobject viapydantic-settings, validated at import. Scatteredos.getenvcalls fail at request time instead of at boot. - Secrets come from the environment, never from source.
Auth
- Enforce with dependencies (
Depends), so it is declarative and cannot be forgotten on a new endpoint. - Never trust a user id from the request body — derive it from the verified token.
Structure
app/
api/ routers
models/ Pydantic models
services/ business logic
db/ database accessHandlers stay thin: validate, delegate to a service, return a model.
Never
- Never return an ORM object directly; map it to a response model.
- Never use
allow_origins=["*"]together with credentials. - Never log secrets, tokens or personal data.
6 formats, one per tool
Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.
---
description: FastAPI conventions
globs: ["app/**/*.py", "**/*.py"]
alwaysApply: false
---
# FastAPI
## Types are the contract
- Every request body is a Pydantic model. **Never `dict` or `Any`** — that
throws away validation, documentation and type safety at once.
- Every endpoint declares a response model, or internal fields leak to clients.
- Annotate return types. They are checked and documented.
## Async
- No blocking I/O inside `async def`. A synchronous driver or `requests` call
stalls the event loop for every other request.
- If a library is synchronous, declare the handler `def` and let FastAPI use a
threadpool.
## Configuration
- One `Settings` object via `pydantic-settings`, validated at import. Scattered
`os.getenv` calls fail at request time instead of at boot.
- Secrets come from the environment, never from source.
## Auth
- Enforce with dependencies (`Depends`), so it is declarative and cannot be
forgotten on a new endpoint.
- Never trust a user id from the request body — derive it from the verified
token.
## Structure
```
app/
api/ routers
models/ Pydantic models
services/ business logic
db/ database access
```
Handlers stay thin: validate, delegate to a service, return a model.
## Never
- Never return an ORM object directly; map it to a response model.
- Never use `allow_origins=["*"]` together with credentials.
- Never log secrets, tokens or personal data.
Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.
What else this module writes
The rule is one file of several. Selecting FastAPI contributes all of this too — merged with every other module you pick, with conflicts resolved rather than duplicated.
DATABASE_URLrequiredConnection string. Full read and write access — never in a client.SECRET_KEYrequiredSigns tokens and sessions. Rotating it invalidates every existing session.ALLOWED_ORIGINSrequiredComma-separated origins allowed by CORS. Never `*` alongside credentials.LOG_LEVELoptionalLogging verbosity.Advisory history
Every time this rule turned out to be wrong, and what we did about it.
This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.
Pro tells you the day a correction lands that affects a repo you actually have.
See what Pro adds →Rules people add alongside this one
The wizard picks the rest of the stack with you, writes all 6 formats, and leaves a manifest so check can tell you when any of it drifts.