Join #headless
on Slack

Multi-site support

Multi-site works differently in Headless Wagtail

The notion of a “site” is different for Headless Wagtail. In traditional Wagtail, the domain or port of a Wagtail site are where Wagtail will serve content and the location the end user visits to find the site.

But in Headless Wagtail, the domain or port that the end user uses and domain or port that Wagtail serves content on will be different. For example, the end user may visit, and the website could be a Next.js app that queries a Wagtail instance running at

Wagtail’s current API implementation will check the host header and port to find the site so that it only returns pages under that site. This means that your site record must be set to However, when Wagtail generates URLs, these URLs need to be generated for

The Wagtail API only allows requests from one site at a time to make sure any site listings are isolated from other sites by default. But the API could be improved in the following ways:

  • Allow the site to be specified in the API request.
  • Allow all pages across all sites to be queried on an opt-in basis.

With these approaches, the site record in the Wagtail admin of Headless Wagtail would be set to the domain or port that the end user sees so URLs could be reversed correctly. All API requests would specify the site as a GET parameter.

Hear the latest news…
Join #headless on Slack