Performing a GET
request against one of the endpoints will get you a listing of objects in that endpoint. The response will look something like this:
GET /api/v1/endpoint_name/
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": "total number of results"
},
"endpoint_name": [
{
"id": 1,
"meta": {
"type": "app_name.ModelName",
"detail_url": "http://api.example.com/api/v1/endpoint_name/1/"
},
"field": "value"
},
{
"id": 2,
"meta": {
"type": "app_name.ModelName",
"detail_url": "http://api.example.com/api/v1/endpoint_name/2/"
},
"field": "different value"
}
]
}
This is the basic structure of all of the listing views. They all have a meta
section with a total_count
variable and a listing of things.
All of the endpoints also contain a "detail" view which returns information on an individual object. This view is always accessed by appending the id of the object to the URL.
This endpoint includes all live pages in your site that have not been put in a private section.
This is what a typical response from a GET
request to this listing would look like:
GET /api/v1/pages/
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 2
},
"pages": [
{
"id": 2,
"meta": {
"type": "demo.HomePage",
"detail_url": "http://api.example.com/api/v1/pages/2/"
},
"title": "Homepage"
},
{
"id": 3,
"meta": {
"type": "demo.BlogIndexPage",
"detail_url": "http://api.example.com/api/v1/pages/3/"
},
"title": "Blog"
}
]
}
Each page object contains the id
, a meta
section and the fields with their values.
This section is used to hold "metadata" fields which aren't fields in the database. Wagtail API adds two by default:
type
- The app label/model name of the objectdetail_url
- A URL linking to the detail view for this object
Most Wagtail sites are made up of multiple different types of page that each have their own specific fields. In order to view/filter/order on fields specific to one page type, you must select that page type using the type
query parameter.
The type
query parameter must be set to the Pages model name in the format: app_label.ModelName
.
GET /api/v1/pages/?type=demo.BlogPage
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 3
},
"pages": [
{
"id": 4,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/4/"
},
"title": "My blog 1"
},
{
"id": 5,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/5/"
},
"title": "My blog 2"
},
{
"id": 6,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/6/"
},
"title": "My blog 3"
}
]
}
As you can see, we still only get the title
field, even though we have selected a type. That's because listing pages require you to explicitly tell it what extra fields you would like to see. You can do this with the fields
query parameter.
Just set fields
to a command-separated list of field names that you would like to use.
GET /api/v1/pages/?type=demo.BlogPage&fields=title,date_posted,feed_image
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 3
},
"pages": [
{
"id": 4,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/4/"
},
"title": "My blog 1",
"date_posted": "2015-01-23",
"feed_image": {
"id": 1,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/1/"
}
}
},
{
"id": 5,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/5/"
},
"title": "My blog 2",
"date_posted": "2015-01-24",
"feed_image": {
"id": 2,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/2/"
}
}
},
{
"id": 6,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/6/"
},
"title": "My blog 3",
"date_posted": "2015-01-25",
"feed_image": {
"id": 3,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/3/"
}
}
}
]
}
We now have enough information to make a basic blog listing with a feed image and date that the blog was posted.
Exact matches on field values can be done by using a query parameter with the same name as the field. Any pages with the field that exactly matches the value of this parameter will be returned.
GET /api/v1/pages/?type=demo.BlogPage&fields=title,date_posted&date_posted=2015-01-24
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 1
},
"pages": [
{
"id": 5,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/5/"
},
"title": "My blog 2",
"date_posted": "2015-01-24",
}
]
}
It is also possible to filter the listing to only include pages with a particular parent or ancestor. This is useful if you have multiple blogs on your site and only want to view the contents of one of them.
child_of
Filters the listing to only include direct children of the specified page.
For example, to get all the pages that are direct children of page 7.
GET /api/v1/pages/?child_of=7
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 1
},
"pages": [
{
"id": 4,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/4/"
},
"title": "Other blog 1"
}
]
}
descendant_of
1.1
Filters the listing to only include descendants of the specified page.
For example, to get all pages underneath the homepage:
GET /api/v1/pages/?descendant_of=2
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 1
},
"pages": [
{
"id": 3,
"meta": {
"type": "demo.BlogIndexPage",
"detail_url": "http://api.example.com/api/v1/pages/3/"
},
"title": "Blog"
},
{
"id": 4,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/4/"
},
"title": "My blog 1",
},
{
"id": 5,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/5/"
},
"title": "My blog 2",
},
{
"id": 6,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/6/"
},
"title": "My blog 3",
}
]
}
Like filtering, it is also possible to order on database fields. The endpoint accepts a query parameter called order
which should be set to the field name to order by. Field names can be prefixed with a -
to reverse the ordering. It is also possible to order randomly by setting this parameter to random
.
GET /api/v1/pages/?type=demo.BlogPage&fields=title,date_posted,feed_image&order=-date_posted
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 3
},
"pages": [
{
"id": 6,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/6/"
},
"title": "My blog 3",
"date_posted": "2015-01-25",
"feed_image": {
"id": 3,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/3/"
}
}
},
{
"id": 5,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/5/"
},
"title": "My blog 2",
"date_posted": "2015-01-24",
"feed_image": {
"id": 2,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/2/"
}
}
},
{
"id": 4,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/4/"
},
"title": "My blog 1",
"date_posted": "2015-01-23",
"feed_image": {
"id": 1,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/1/"
}
}
}
]
}
Pagination is done using two query parameters called limit
and offset
. limit
sets the number of results to return and offset
is the index of the first result to return. The default value for limit
is 20
and its maximum value is 100
(which can be changed using the WAGTAILAPI_MAX_RESULTS
setting).
GET /api/v1/pages/?limit=1&offset=1
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 2
},
"pages": [
{
"id": 3,
"meta": {
"type": "demo.BlogIndexPage",
"detail_url": "http://api.example.com/api/v1/pages/3/"
},
"title": "Blog"
}
]
}
Pagination will not change the total_count
value in the meta.
To perform a full-text search, set the search
parameter to the query string you would like to search on.
GET /api/v1/pages/?search=Blog
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 3
},
"pages": [
{
"id": 3,
"meta": {
"type": "demo.BlogIndexPage",
"detail_url": "http://api.example.com/api/v1/pages/3/"
},
"title": "Blog"
},
{
"id": 4,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/4/"
},
"title": "My blog 1",
},
{
"id": 5,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/5/"
},
"title": "My blog 2",
},
{
"id": 6,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/6/"
},
"title": "My blog 3",
}
]
}
The results are ordered by relevance. It is not possible to use the order
parameter with a search query.
If your Wagtail site is using Elasticsearch, you do not need to select a type to access specific fields. This will search anything that's defined in the models' search_fields
.
This view gives you access to all of the details for a particular page.
GET /api/v1/pages/6/
HTTP 200 OK
Content-Type: application/json
{
"id": 6,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/6/"
},
"parent": {
"id": 3,
"meta": {
"type": "demo.BlogIndexPage",
"detail_url": "http://api.example.com/api/v1/pages/3/"
}
},
"title": "My blog 3",
"date_posted": "2015-01-25",
"feed_image": {
"id": 3,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/3/"
}
},
"related_links": [
{
"title": "Other blog page",
"page": {
"id": 5,
"meta": {
"type": "demo.BlogPage",
"detail_url": "http://api.example.com/api/v1/pages/5/"
}
}
}
]
}
- The format is the same as that which is returned inside the listing view, with two additions:
- All of the available fields are added to the detail page by default
- A
parent
field has been included that contains information about the parent page
This endpoint gives access to all uploaded images. This will use the custom image model if one was specified. Otherwise, it falls back to wagtailimages.Image
.
This is what a typical response from a GET
request to this listing would look like:
GET /api/v1/images/
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 3
},
"images": [
{
"id": 4,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/4/"
},
"title": "Wagtail by Mark Harkin"
},
{
"id": 5,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/5/"
},
"title": "James Joyce"
},
{
"id": 6,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/6/"
},
"title": "David Mitchell"
}
]
}
Each image object contains the id
and title
of the image.
Like the pages endpoint, the images endpoint supports the fields
query parameter.
By default, this will allow you to add the width
and height
fields to your results. If your Wagtail site uses a custom image model, it is possible to have more.
GET /api/v1/images/?fields=title,width,height
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 3
},
"images": [
{
"id": 4,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/4/"
},
"title": "Wagtail by Mark Harkin",
"width": 640,
"height": 427
},
{
"id": 5,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/5/"
},
"title": "James Joyce",
"width": 500,
"height": 392
},
{
"id": 6,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/6/"
},
"title": "David Mitchell",
"width": 360,
"height": 282
}
]
}
Exact matches on field values can be done by using a query parameter with the same name as the field. Any images with the field that exactly matches the value of this parameter will be returned.
GET /api/v1/pages/?title=James Joyce
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 3
},
"images": [
{
"id": 5,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/5/"
},
"title": "James Joyce"
}
]
}
The images endpoint also accepts the order
parameter which should be set to a field name to order by. Field names can be prefixed with a -
to reverse the ordering. It is also possible to order randomly by setting this parameter to random
.
GET /api/v1/images/?fields=title,width&order=width
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 3
},
"images": [
{
"id": 6,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/6/"
},
"title": "David Mitchell",
"width": 360
},
{
"id": 5,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/5/"
},
"title": "James Joyce",
"width": 500
},
{
"id": 4,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/4/"
},
"title": "Wagtail by Mark Harkin",
"width": 640
}
]
}
Pagination is done using two query parameters called limit
and offset
. limit
sets the number of results to return and offset
is the index of the first result to return. The default value for limit
is 20
and its maximum value is 100
(which can be changed using the WAGTAILAPI_MAX_RESULTS
setting).
GET /api/v1/images/?limit=1&offset=1
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 3
},
"images": [
{
"id": 5,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/5/"
},
"title": "James Joyce",
"width": 500,
"height": 392
}
]
}
Pagination will not change the total_count
value in the meta.
To perform a full-text search, set the search
parameter to the query string you would like to search on.
GET /api/v1/images/?search=James
HTTP 200 OK
Content-Type: application/json
{
"meta": {
"total_count": 1
},
"pages": [
{
"id": 5,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/5/"
},
"title": "James Joyce",
"width": 500,
"height": 392
}
]
}
Like the pages endpoint, the results are ordered by relevance and it is not possible to use the order
parameter with a search query.
This view gives you access to all of the details for a particular image.
GET /api/v1/images/5/
HTTP 200 OK
Content-Type: application/json
{
"id": 5,
"meta": {
"type": "wagtailimages.Image",
"detail_url": "http://api.example.com/api/v1/images/5/"
},
"title": "James Joyce",
"width": 500,
"height": 392
}
This endpoint gives access to all uploaded documents.
The documents listing supports the same features as the images listing (documented above) but works with Documents instead.
This view gives you access to all of the details for a particular document.
GET /api/v1/documents/1/
HTTP 200 OK
Content-Type: application/json
{
"id": 1,
"meta": {
"type": "wagtaildocs.Document",
"detail_url": "http://api.example.com/api/v1/documents/1/",
"download_url": "http://api.example.com/documents/1/usage.md"
},
"title": "Wagtail API usage"
}