Responder

Web services for humans.
A familiar HTTP Service Framework for Python, powered by Starlette.

Documentation · Quickstart · Tour · Examples · Changelog

import responder
api = responder.API()
@api.get("/hello/{name}") def hello(req, resp, *, name):     resp.media = {"hello": name}
if name == "main":     api.run()

$ pip install responder
$ python app.py

Open http://127.0.0.1:5042/hello/world. That's it.

Responder is the friendly request/response shape of Flask and Falcon, brought to ASGI with Starlette underneath. Every view receives a req and a resp. Read from one, write to the other. Sync and async views both work.

Why Responder?

Responder is for people who like small, expressive web frameworks with real batteries included.

| You want | Responder gives you | | --- | --- | | A simple mental model | def view(req, resp): ... with mutable request and response objects | | Modern Python I/O | ASGI, Starlette routing, uvicorn by default, optional Granian | | Real API contracts | Pydantic request/response models and generated OpenAPI 3.0/3.1 | | Pleasant responses | resp.text, resp.html, resp.media, resp.file(), resp.problem() | | Production ergonomics | request IDs, structured logging, rate limiting, health checks, metrics | | Safer defaults | Problem Details errors, capped request bodies, secure session guidance | | Escape hatches | mount Flask, Django, WSGI, ASGI apps, or plain routers under one API |

The Shape

Routes look like Python strings, because they are meant to be read.

@api.get("/users/{user_id:int}")
def getuser(req, resp, *, userid):
    resp.media = {"id": user_id, "name": "Ada"}

Write the response you mean:

resp.text = "hello"
resp.html = "<h1>Hello</h1>"
resp.media = {"ok": True}       # JSON by default, YAML/msgpack by negotiation
resp.file("report.pdf")         # content type detected for you
resp.status_code = 201
resp.headers["Location"] = "/items/1"

Read requests without ceremony:

@api.post("/echo")
async def echo(req, resp):
    payload = await req.media()
    resp.media = {"you_sent": payload}

Return values work too, when that style feels right:

@api.get("/ping")
def ping(req, resp):
    return {"pong": True}

A Real Endpoint

Responder can stay tiny, but it does not stop at toy apps.

from pydantic import BaseModel, Field
import responder from responder.ext.auth import BearerAuth
class ItemIn(BaseModel):     name: str = Field(min_length=1)     price: float = Field(gt=0)
class ItemOut(ItemIn):     id: int
class User(BaseModel):     name: str     scopes: list[str]
api = responder.API(     title="Store API",     version="1.0",     openapi="3.1.0",     docs_route="/docs",     request_id=True, )
users = {"secret-token": User(name="Ada", scopes=["items:write"])} auth = BearerAuth(verify=lambda token: users.get(token), bearer_format="opaque") writer = api.policy("writer", auth.requires("items:write"))
@api.post(     "/items",     auth=writer,     status_code=201,     summary="Create an item", ) def create_item(req, resp, *, item: ItemIn, user) -> ItemOut:     return ItemOut(id=1, **item.model_dump())

You get validation, auth enforcement, a documented request body, a documented response body, 401/403/422 Problem Details responses, request IDs, and Swagger UI at /docs.

What's Included

| Area | Highlights | | --- | --- | | Routing | @api.get, @api.post, route groups, class-based views, typed path convertors | | Validation | Pydantic body models, query/header/cookie markers, typed response models | | OpenAPI | OpenAPI 3.0/3.1, Swagger UI, examples, security schemes, generated clients | | Responses | JSON/YAML/msgpack negotiation, files, streaming, SSE, byte ranges, ETags | | Security | signed sessions, server-side sessions, CSRF protection, auth helpers, JWT/OAuth2 | | Operations | request IDs, structured access logs, health checks, Prometheus metrics | | Limits | request body caps, streaming multipart uploads, in-memory/Redis rate limiting | | Composition | dependencies with teardown, background tasks, WSGI/ASGI mounting, WebSockets | | Deployment | built-in uvicorn runner, optional Granian, proxy-header support | | Testing | in-process api.requests and configurable api.test_client(...) |

v9 Highlights

Responder 9 tightened the production story while keeping the familiar API:

• Multipart uploads stream from the wire and spool to disk instead of buffering

entire files in memory.

• Request bodies are capped at 100 MiB by default; pass

API(maxrequestsize=None) for the legacy unlimited behavior.

• API(csrf=True) adds session-bound CSRF protection for unsafe requests, with

per-route opt-outs for webhooks.

• API(trustproxyheaders=True) rewrites scheme, host, and client IP from

trusted reverse-proxy headers.

• Framework-generated errors use RFC 9457-style application/problem+json

responses by default.

• OpenAPI documents operational responses such as CSRF 403, body-cap 413,

rate-limit 429, fail-closed limiter 503, validation 422, and timeout 504 where they can actually happen.

Upgrading from an earlier major version? Start with the v9 migration guide.

Installation

$ pip install responder

Python 3.11 and newer are supported.

Optional extras:

$ pip install "responder[server]"   # Granian production server
$ pip install "responder[graphql]"  # GraphQL with Graphene
$ pip install "responder[jwt]"      # JWT auth helpers
$ pip install "responder[orjson]"   # orjson JSON backend

With uv:

$ uv add responder

Run It

# app.py
import responder
api = responder.API()
@api.get("/") def index(req, resp):     resp.text = "hello, world!"
if name == "main":     api.run(port=8000)

$ python app.py

Or through the CLI:

$ responder run app.py

OpenAPI and Clients

Turn on OpenAPI with two arguments:

api = responder.API(
    title="Acme API",
    version="1.0",
    openapi="3.1.0",
    docs_route="/docs",
)

Responder builds the schema from routes, type hints, Pydantic models, auth helpers, and framework behavior. The docs UI appears at /docs, the schema at /schema.yml, and client code can be generated for Python, JavaScript, TypeScript, Ruby, and PHP.

$ responder client --class-name StoreClient --output store_client.py app:api

Examples Worth Reading

| Example | Why it is useful | | --- | --- | | examples/atelier.py | The golden contract app: auth, policies, examples, OpenAPI, generated-client coverage | | examples/todo.py | A practical typed Todo API with protected writes and polished schema metadata | | examples/fortunes.py | Tiny app wrapping the local fortune CLI tool | | examples/tarot.py | A playful API that shuffles, lists, and deals tarot cards | | examples/sse_stream.py | Server-Sent Events and streaming responses | | examples/websocket_chat.py | WebSocket chat with Responder's route style | | examples/marimo_mount.py | Mounting a marimo notebook app under Responder |

Run most examples with:

$ responder run examples/todo.py

Philosophy

Responder is intentionally familiar. If you know Flask, Falcon, Requests, or Starlette, you already know most of the ideas. The framework tries to make the simple thing feel natural, then keeps enough power nearby for real services: typed contracts, OpenAPI, auth, rate limiting, streaming uploads, websockets, and production middleware.

It is a passion project and a practical toolkit. It is especially good for personal services, internal tools, prototypes, teaching, research apps, and small APIs where clarity matters more than ceremony.

Documentation

The full guide lives at responder.kennethreitz.org.

• Quickstart
• Tour
• Examples
• Deployment
• Testing
• API reference
• Changelog

License

Apache-2.0.