Wagtail API v3

Wagtail 8.0 introduces a v3 API built on Django Ninja and Pydantic. It provides OpenAPI 3.1 schema export and declarative per-type schemas to support read and write CMS operations described in RFC 115.

The v2 read API remains available. v3 is mounted separately at /api/v3/.

Quick start

Register the API URLs in your project:

# urls.py
from wagtail.api.v3.urls import api

urlpatterns = [
    path("api/v3/", api.urls),
]

Browse the interactive docs at /api/v3/docs and the OpenAPI schema at /api/v3/openapi.json.

The v3 API reads the same WAGTAILAPI_* settings as v2 where applicable (WAGTAILAPI_BASE_URL, WAGTAILAPI_LIMIT_MAX, WAGTAILAPI_SEARCH_ENABLED). See Wagtail API v2 configuration guide and the API settings reference.

Pagination

List endpoints use Django Ninja’s limit/offset pagination:

{
    "count": 42,
    "items": []
}

count is the total number of results irrespective of pagination. Use ?limit and ?offset query parameters to page through results. WAGTAILAPI_LIMIT_MAX caps the maximum limit value (see Wagtail API v2 configuration guide and the API settings reference).

Error format

All error responses use RFC 7807 application/problem+json:

{
    "type": "https://docs.wagtail.org/api/v3/validation-error",
    "title": "Unprocessable Entity",
    "status": 422,
    "detail": "Validation failed",
    "errors": []
}