API development

Guidance for Wagtail core contributors working on the v3 API transport layer first defined in RFC 115.

OpenAPI snapshot workflow

CI asserts that api.get_openapi_schema() matches wagtail/api/v3/tests/snapshots/openapi.json.

When you add or change endpoints intentionally, regenerate the snapshot and commit the changes:

make openapi-snapshot

For guidance on the v3 API’s schema discovery endpoints and how read and write schemas are generated, see the schema discovery guide.

Type checking

The v3 API package is type-checked with ty (configured in [tool.ty] in pyproject.toml). Checking is scoped to wagtail/api/v3 only.

Pagination

List endpoints use @paginate with WagtailLimitOffsetPagination, defined in wagtail/api/v3/pagination.py. Responses use Ninja’s native envelope: {"count": N, "items": [...]}. WAGTAILAPI_LIMIT_MAX is enforced in the paginator.

RFC 7807 errors

Register handlers via register_exception_handlers(api) in wagtail/api/v3/errors.py. Tests should use assert_problem_response from wagtail.api.v3.tests.base.