Redirects

Redirects are managed at /api/v3/redirects/. Reads are public for anonymous requests; writes require an authenticated request. See v3 API authentication for how tokens map to permissions.

Redirects are exposed as CRUD:

  • GET /redirects/: list redirects. Public for anonymous read.

  • GET /redirects/find/: resolve a redirect and redirect to its canonical detail. Public for anonymous read.

  • GET /redirects/{redirect_id}/: return one redirect. Public for anonymous read.

  • POST /redirects/: create a redirect. Requires a token.

  • PUT /redirects/{redirect_id}/: update a redirect. Requires a token.

  • DELETE /redirects/{redirect_id}/: delete a redirect. Requires a token.

Redirect reads are public because the redirect middleware resolves redirects publicly; the endpoints behave like the v2 API in this regard.

A redirect is described by its id, old_path, nullable site_id, is_permanent, redirect_page_id, redirect_page_route_path, redirect_link, automatically_created, and created_at. The list supports exact filtering and ordering but not search.

The find endpoint resolves html_path through Wagtail’s redirect middleware, or falls back to matching by id, then responds with a 302 redirect to the canonical detail:

curl "https://example.com/api/v3/redirects/find/?html_path=/old-page/"

Note

As with page find, the OpenAPI schema describes find as returning the redirect detail schema, but the runtime response is a 302 redirect. Clients generated from OpenAPI should follow the redirect to the detail URL.

Creates and updates go through RedirectForm, which provides path normalization and duplicate validation. Redirects are not swappable, and redirect CRUD instantiates the generic action classes directly, so project action-registry overrides do not affect redirect mutations.

Example: create a redirect and resolve it

This example redirects an old missing URL to an existing page, then resolves the old path. It assumes a BASE pointing at the mounted API, a bearer TOKEN, and an existing page with ID 9.

Create the redirect with the old path and the destination page:

curl -X POST "$BASE/redirects/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"old_path": "/old-location/", "redirect_page_id": 9, "is_permanent": true}'

Resolve the old path. The endpoint follows the redirect and returns the canonical redirect detail:

curl "$BASE/redirects/find/?html_path=/old-location/"

Redirects API reference

We document the full generated OpenAPI reference for every image endpoint from Wagtail’s own OpenAPI snapshot, see v3 API reference.