Skip to main content

​
Overview

The Pages API endpoint provides access to all published pages in the Wagtail CMS. You can retrieve page listings, individual pages, and filter by type or fields.

​
Endpoint

GET /api/v2/pages/

​
List All Pages

Retrieve a list of all published pages: 
curl http://localhost:8000/api/v2/pages/

​
Response

{
  "meta": {
    "total_count": 15
  },
  "items": [
    {
      "id": 3,
      "meta": {
        "type": "home.HomePage",
        "detail_url": "http://localhost:8000/api/v2/pages/3/",
        "html_url": "http://localhost:8000/",
        "slug": "home",
        "first_published_at": "2024-01-15T10:30:00Z"
      },
      "title": "Home"
    }
  ]
}

​
Get Single Page

Retrieve a specific page by ID: 
curl http://localhost:8000/api/v2/pages/3/

​
Response

{
  "id": 3,
  "meta": {
    "type": "home.HomePage",
    "detail_url": "http://localhost:8000/api/v2/pages/3/",
    "html_url": "http://localhost:8000/",
    "slug": "home",
    "show_in_menus": true,
    "seo_title": "",
    "search_description": "",
    "first_published_at": "2024-01-15T10:30:00Z",
    "parent": {
      "id": 1,
      "meta": {
        "type": "wagtailcore.Page",
        "detail_url": "http://localhost:8000/api/v2/pages/1/"
      },
      "title": "Root"
    }
  },
  "title": "Home"
}

​
Query Parameters

​
type
string
Filter pages by type (e.g., blog.BlogPage, home.HomePage)
​
child_of
integer
Return only pages that are children of the specified page ID
​
descendant_of
integer
Return only pages that are descendants of the specified page ID
​
fields
string
Comma-separated list of fields to include. Use * for all fields.
​
limit
integer
default:"20"
Number of results per page (max 100)
​
offset
integer
default:"0"
Number of results to skip
​
order
string
Field to order by. Prefix with - for descending (e.g., -first_published_at)
​
search
string
Search query to filter pages by title and content

​
Response Fields

​
Default Fields

By default, the API returns minimal fields:
​
id
integer
Unique identifier for the page
​
title
string
The page title
​
meta
object
Metadata about the page
​
type
string
The page model type (e.g., blog.BlogPage)
​
detail_url
string
API URL for the full page details
​
html_url
string
Public URL of the page on the website
​
slug
string
URL slug for the page
​
first_published_at
string
ISO 8601 timestamp of first publication

​
All Fields

Request all fields using ?fields=*: 
curl "http://localhost:8000/api/v2/pages/3/?fields=*"
This includes additional page-type-specific fields like body content, images, and custom fields defined in your page models.

​
Filtering Examples

​
Filter by Page Type

Get only blog pages: 
curl "http://localhost:8000/api/v2/pages/?type=blog.BlogPage"

​
Get Child Pages

Get all direct children of a page: 
curl "http://localhost:8000/api/v2/pages/?child_of=3"

​
Get All Descendants

Get all descendants of a page (children, grandchildren, etc.): 
curl "http://localhost:8000/api/v2/pages/?descendant_of=3"

​
Search Pages

Search for pages containing specific text: 
curl "http://localhost:8000/api/v2/pages/?search=bread"

​
Combine Filters

Combine multiple filters and parameters: 
curl "http://localhost:8000/api/v2/pages/?type=blog.BlogPage&fields=*&order=-first_published_at&limit=5"
This returns the 5 most recent blog pages with all fields included.

​
Common Page Types

The Wagtail Bakery Demo includes these page types:
TypeDescription
home.HomePageHomepage with hero sections
blog.BlogIndexPageBlog listing page
blog.BlogPageIndividual blog post
breads.BreadIndexPageBread catalog listing
breads.BreadPageIndividual bread product
locations.LocationsIndexPageLocations listing
locations.LocationPageIndividual location

​
Best Practices

Always use the fields parameter to request only the data you need. This improves performance and reduces bandwidth.

​
Request Specific Fields

Instead of requesting all fields with *, specify only what you need: 
curl "http://localhost:8000/api/v2/pages/?fields=title,first_published_at,slug"

​
Use Pagination

For large datasets, use pagination to avoid timeouts: 
curl "http://localhost:8000/api/v2/pages/?limit=50&offset=0"

​
Cache Responses

Consider caching API responses on the client side to reduce server load and improve performance.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us