Skip to content

Guide

This is the reference guide: one topic per page, each covering a single part of Django Ninja completely — how it works, every option, and the edge cases. If you're starting out, do the Quick Start or Tutorial first; come back here when you need the details on a specific feature.

Every page is self-contained and can be read on its own, but the pages build on a few core objects that are worth knowing about upfront.

The core pieces

  • NinjaAPI — the root object. You create one per project (or one per API version), then wire it into urls.py. It's also where you configure global concerns like authentication, throttling, exception handlers, CSRF, OpenAPI/docs URLs and versioning.
  • Operations — an operation is a single endpoint: the combination of an HTTP method, a URL path and a Python function (@api.get(...), @api.post(...), etc.).
  • Routers — a way to group related operations and mount them under a prefix, similar to Django's own include(). Used to split a large API into modules.
  • Schemas — Pydantic models used to declare the shape of request bodies and responses, and to generate the OpenAPI schema and interactive docs automatically.

A minimal API using all four looks like this:

from ninja import NinjaAPI, Router, Schema

api = NinjaAPI()
router = Router()


class HelloResponse(Schema):
    message: str


@router.get("/hello", response=HelloResponse)
def hello(request, name: str = "world"):
    return {"message": f"Hello, {name}"}


api.add_router("/greetings", router)

What's covered

The rest of the guide is grouped by what you're trying to do:

Handling requests

Schemas

Producing responses

Cross-cutting concerns

Tooling