Rest API Technical Reference

Overview

Note: This page is a technical reference for the Rest API. If you're starting a project with Prismic, we recommend that you use find a user-friendly guide in for the technology of your choice in our technology guides.

The Prismic Rest API is an extremely fast, flexible, and powerful engine for your content. Your API endpoint is available here:

Copy
https://your-repo-name.cdn.prismic.io/api/v2

At this endpoint, you will find the meta information about your Prismic repo, including languages, and Custom Types. Importantly, this endpoint includes an array containing your repo's refs.

What is a ref?

A ref is a reference to a specific version of your content (for instance: draft, published, or scheduled). To query your content, you will need to perform one query to get your current ref (which is a short token), and then a second query — using that ref — to get your content. This ensures that the content returned is the right version and up-to-date.

Our API development kits, such as @prismicio/client, provide query helper functions that perform the first query for you, so you don't need to worry about it.

A standard content query could look like this:

Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=X71BaxIAACMA0NsN&access_token=MTYwNjMyMjI1NzU5MS5YNzU2UVJJQUFDQUExaV8z.HO-_ve-_ve-_vTpKbSfvv73vv73vv73vv70e77-9CW04B--_ve-_vWJ_b00U77-9Je-_vRoh77-977-9&q=%5B%5Bat(document.type%2C%22post%22)%5D%5D&orderings=%5Bdocument.first_publication_date%20desc%5D

Your query is defined with a query string (everything in the URL that comes after the question mark). The query string is made up of name–value pairs, called parameters, which are joined with ampersands (&) and formatted as name=value. Each value is encoded using JavaScript's built-in encodeURIComponent() function.

You can use the following parameters to construct your query string:

  • ref (required): A short token to specify which version of your content to query. Available at your main API endpoint.
  • access_token: A long, secret string required to query private content (such as content in private repos and drafts). Available in your Prismic repo settings.
  • q: A query parameter to filter your content. If omitted, the API will return all documents.
  • orderings, lang, graphQuery, etc: Option parameters to further customize your query.

Now let's break down the parameters of the above query:

Copy
// the ref specifies what version of your content to query
ref=X71BaxIAACMA0NsN

// the access token is required to view private content
access_token=MTYwNjMyMjI1NzU5MS5YNzU2UVJJQUFDQUExaV8z.HO-_ve-_ve-_vTpKbSfvv73vv73vv73vv70e77-9CW04B--_ve-_vWJ_b00U77-9Je-_vRoh77-977-9

// the query parameter is an encoded predicate
q=%5B%5Bat(document.type%2C%22post%22)%5D%5D

// orderings is one example of a query option
orderings=%5Bdocument.first_publication_date%20desc%5D

Query Predicates

The query parameter (q) accepts a set of predicates (encoded as a URI component) as its value. Each predicate is enclosed in square brackets, and the set is enclosed is square brackets.

What is a predicate?

A predicate is a search argument. It tells the API what content to search for. Prismic has dozens of built-in predicates, which can each accept countless variables — making for infinitely flexible querying. As an example, the predicate "at" seeks an exact match between a field of your document and a value you provide. So, at(document.type, "post") looks for all documents that have a "type" matching "post." Similarly, there are predicates for "not," "any," "date," and much more.

If the set includes multiple predicates, or if the query string contains multiple query parameters, the API will return documents that match every predicate.

Most predicates accept a path to denote the field being examined and then one or more values to compare in the search. The paths can take two formats, based on the predicate: document.[meta-value] or my.[custom-type].[field]. See the full path reference below.

A basic query parameter to search for a document of type "article" will look like this:

  • Unencoded
  • Encoded
Copy
[[at(document.type,"article")]]
Copy
%5B%5Bat(document.type%2C%22article%22)%5D%5D

A query parameter to search for a document of type "article," last published in 2017, will look like this:

  • Unencoded
  • Encoded
Copy
[[at(document.type,"article")][date.year(document.last_publication_date,2017)]]
Copy
%5B%5Bat(document.type%2C%22article%22)%5D%5Bdate.year(document.last_publication_date%2C2017)%5D%5D

To build your queries, we recommend that you use the Prismic API Browser. You can access the API Browser at https://your-repo-name.prismic.io/api/v2. (Learn more about the API Browser.)

In general, you won't need to construct query URLs, because we have development kits for most popular web development frameworks. These kits offer helper functions for querying the API. You can learn more about querying with various technologies in our technology guides.

Here's an example of what a predicate query would look like in the API Browser, with our JavaScript kit, and as a URL:

  • API Browser
  • JavaScript
  • URL
Copy
[date.year(document.last_publication_date,2016)]
[at(document.type,"blog-post")]






Copy
const Prismic = require('prismic-javascript') 
const apiEndpoint = 'https://your-repo-name.cdn.prismic.io/api/v2' 
const client = Prismic.client(apiEndpoint)

client.query([
  Prismic.Predicates.year('document.last_publication_date', 2016),
  Prismic.Predicates.at('document.type', 'blog-post')
])
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bdate.year(document.last_publication_date%2C2016)%5D%5Bat(document.type%2C%22blog-post%22)%5D%5D







Here is the full list of predicates:

at

Checks that the path matches the described value exactly. It takes a single value for a field or an array (only for tags).

  • API Browser
  • JavaScript
  • URL
Copy
[at(path, value)]
Copy
Prismic.Predicates.at( path, value )
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=your_ref&at(path%2Cvalue)%5D%5D

Available values:

path

document.type

document.tags

document.id

my.[custom-type].[uid-field]

my.[custom-type].[key-text-field]

my.[custom-type].[select-field]

my.[custom-type].[number-field]

my.[custom-type].[date-field]

my.[custom-type].[boolean-field]

value

single value (for all but document.tags)

array of values (only for document.tags)

Examples:

  • API Browser
  • JavaScript
  • URL
Copy
// All documents of type "product"
[at(document.type, "product")]

// All documents with the tags "Macaron" and "Cupcake"
[at(document.tags, ["Macaron", "Cupcake"])]

// All documents of type "product" with a "price" of 50
[at(my.product.price, 50)]
Copy
// All documents of type "product"
Prismic.Predicates.at('document.type', 'product')

// All documents with the tags "Macaron" and "Cupcake"
Prismic.Predicates.at('document.tags', ['Macaron', 'Cupcake'])

// All documents of type "product" with a "price" of 50
Prismic.Predicates.at('my.product.price', 50)
Copy
// All documents of type "product"
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bat(document.type%2C%22product%22)%5D%5D

// All documents with the tags "Macaron" and "Cupcake"
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bat(document.tags%2C%5B%22Macaron%22%2C%22Cupcake%22%5D)%5D%5D

// All documents of type "product" with a "price" of 50
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bat(my.product.price%2C50)%5D%5D

not

Checks that the path doesn't match the provided value exactly. It takes a single value as the argument.

  • API Browser
  • JavaScript
  • URL
Copy
[not( path, value )]
Copy
Prismic.Predicates.not( path, value )
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bnot(path%2Cvalue)%5D%5D

Accepted values:

path

document.type

document.tags

document.id

my.[custom-type].[uid-field]

my.[custom-type].[key-text-field]

my.[custom-type].[select-field]

my.[custom-type].[number-field]

my.[custom-type].[date-field]

my.[custom-type].[boolean-field]

value

single value

Example:

  • API Browser
  • JavaScript
  • URL
Copy
[not(document.type, 'product')]
Copy
Prismic.Predicates.not('document.type', 'product')
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bnot(document.type%2C%22product%22)%5D%5D

any

Accepts an array of values, and checks whether the fragment matches any of the values in the array. When used with the ID or UID field, it will not necessarily return the documents in the order given in the array.

  • API Browser
  • JavaScript
  • URL
Copy
[any( path, values )]
Copy
Prismic.Predicates.any( path, values )
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bany(path%2Cvalues)%5D%5D

Accepted values:

path

document.type

document.tags

document.id

my.[custom-type].[uid-field]

my.[custom-type].[key-text-field]

my.[custom-type].[select-field]

my.[custom-type].[number-field]

my.[custom-type].[date-field]

value

array of values

Example:

  • API Browser
  • JavaScript
  • URL
Copy
[any(document.type, ['product', 'blog-post'])]
Copy
Prismic.Predicates.any('document.type', ['product', 'blog-post'])
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bany(document.type%2C%5B%22product%22%2C%22blog-post%22%5D)%5D%5D

in

Checks whether a document's ID or UID is in an array of IDs or UIDs. It works the same as the any predicate, but is much faster because it is only used for IDs and UIDs.

Also, unlike the any predicate, it returns the documents in the same order as the given array.

  • API Browser
  • JavaScript
  • URL
Copy
[in( path, array )]
Copy
Prismic.Predicates.in( path, array )
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bin(path%2Carray)%5D%5D

Accepted values:

path

document.id

my.[custom-type].uid

value

array of IDs or UIDs

Example with IDs:

  • API Browser
  • JavaScript
  • URL
Copy
[in(document.id,['Wl4CCCcAAAfU5RMd','WiU34h0AAI90y1m2'])]
Copy
Prismic.Predicates.in("document.id",['Wl4CCCcAAAfU5RMd','WiU34h0AAI90y1m2'])
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bin(document.id%2C%5B%22Wl4CCCcAAAfU5RMd%22%2C%22WiU34h0AAI90y1m2%22%5D)%5D%5D

Example with UIDs:

  • API Browser
  • JavaScript
  • URL
Copy
[in(my.page.uid,['hello-world','about-me'])]
Copy
Prismic.Predicates.in("my.page.uid",['hello-world','about-me'])
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bin(my.page.uid%2C%5B%22hello-world%22%2C%22about-me%22%5D)%5D%5D

fulltext

Checks if a string is found inside a whole document or within a specific field on a document.

fulltext will search for a single term, passed as a string, or for multiple terms, passed as a string of terms with spaces between them. With multiple terms, the API will return documents that contain all terms.

The search is not case-sensitive and it matches based on the root word, so a search for "Dogs" will include "dog."

The search considers Rich Text, Title, Key Text, Select, and UID fields. It ignores image alt text in Rich Text fields. It doesn't matter if the field is inside a Group, a Slice, or a Slice repeatable section.

The search is ordered by relevance, with more priority given to Rich Text content, especially headings.

  • API Browser
  • JavaScript
  • URL
Copy
[fulltext( path, value )]
Copy
Prismic.Predicates.fulltext( path, value )
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bfulltext(path%2Cvalue)%5D%5D

Accepted values:

path

document

my.[custom-type].[rich-text-field]

my.[custom-type].[title-field]

my.[custom-type].[key-text-field]

my.[custom-type].[uid]

my.[custom-type].[select-field]

value

string

Example:

  • API Browser
  • JavaScript
  • URL
Copy
// all documents that contain the word "quickstart"
[fulltext(document,'quickstart')]

// all page documents with a description that contains the words "configuration" and "endpoint"
[fulltext(my.page.description,'configuration endpoint')]
Copy
// all documents that contain the word "quickstart"
Prismic.Predicates.fulltext('document','quickstart')

// all page documents with a description that contains the words "configuration" and "endpoint"
Prismic.Predicates.fulltext('my.page.description','configuration endpoint')
Copy
// all documents that contain the word "quickstart"
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bfulltext(document%2C%22quickstart%22)%5D%5D

// all page documents with a description that contains the words "configuration" and "endpoint"
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bfulltext(my.page.description%2C%22configuration%20endpoint%22)%5D%5D

has

The has predicate checks whether a fragment has a value. It will return all the documents of the specified type that contain a value for the specified field.

Works for all content types except Groups and Slices.

  • API Browser
  • JavaScript
  • URL
Copy
[has( path )]
Copy
Prismic.Predicates.has( path )
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bfulltext(my.page.description%2C%22configuration%20endpoint%22)%5D%5D

Accepted values:

path

my.[custom-type].[field]

Example:

  • API Browser
  • JavaScript
  • URL
Copy
// all "page" documents that have a description
[has(my.page.description)]
Copy
// all "page" documents that have a description
Prismic.Predicates.has("my.page.description")
Copy
// all "page" documents that have a description
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bhas(my.page.description)%5D%5D

missing

The missing predicate checks if a fragment doesn't have a value. It will return all the documents of the specified type that do not contain a value for the specified field.

Works for all content types except Groups and Slices.

Note that this predicate will restrict the results to the custom type implied in the path.

  • API Browser
  • JavaScript
  • URL
Copy
[missing( path )]
Copy
Prismic.Predicates.missing( path )
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bmissing(path)%5D%5D

Accepted values:

path

my.[custom-type].[field]

Example:

  • API Browser
  • JavaScript
  • URL
Copy
[missing(my.page.description)]
Copy
Prismic.Predicates.missing("my.page.description")
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bmissing(my.page.description)%5D%5D

similar

The similar predicate takes the ID of a document, and returns a list of documents with similar content. This allows you to build an automated content discovery feature (for example, a "Related posts" section).

  • API Browser
  • JavaScript
  • URL
Copy
[similar( id, value )]
Copy
Prismic.Predicates.similar( id, value)
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bsimilar(id%2C%20value)%5D%5D

Accepted values:

value

A document ID

path

The maximum number of documents that a term may appear in to still be considered relevant

Example:

  • API Browser
  • JavaScript
  • URL
Copy
[similar("WiU34h0AAI90y1m2", 10)]
Copy
Prismic.Predicates.similar("WiU34h0AAI90y1m2", 10)
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bsimilar(%22WiU34h0AAI90y1m2%22%2C%2010)%5D%5D

near

The geopoint.near predicate checks that the value in the path is within the radius of the given coordinates. Distance is measured in kilometers.

The near predicate will order the results from nearest to farthest from the given coordinates.

  • API Browser
  • JavaScript
  • URL
Copy
[geopoint.near( path, latitude, longitude, radius )]
Copy
Prismic.Predicates.near( path, latitude, longitude, radius )
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bgeopoint.near(%20path%2C%20latitude%2C%20longitude%2C%20radius%20)%5D%5D

Accepted values:

path

my.[custom-type].[geopoint-field]

latitude

Latitude of the center of the search area

longitude

Longitude of the center of the search area

radius

Radius of search in kilometers

Example:

  • API Browser
  • JavaScript
  • URL
Copy
[geopoint.near(my.restaurant.location, 9.656896299, -9.77508544, 10)]
Copy
Prismic.Predicates.near("my.restaurant.location", 9.656896299, -9.77508544, 10)
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5Bgeopoint.near(my.restaurant.location%2C%209.656896299%2C%20-9.77508544%2C%2010)%5D

lt

The number.lt predicate checks that the value in the number field is less than the value passed into the predicate.

This is a strict less-than operator, it will not give values equal to the specified value.

  • API Browser
  • JavaScript
  • URL
Copy
[number.lt( path, value )]
Copy
Prismic.Predicates.lt( path, value )
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bnumber.lt(%20path%2C%20value%20)%5D%5D%0A

Accepted values:

path

my.[custom-type].[number-field]

value

Number

Example:

  • API Browser
  • JavaScript
  • URL
Copy
[number.lt(my.product.price, 9.99)]
Copy
Prismic.Predicates.lt("my.product.price", 9.99)
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bnumber.lt(%20my.product.price%2C%209.99%20)%5D%5D

gt

The number.gt predicate checks that the value in the number field is greater than the value passed into the predicate.

This is a strict greater-than operator, it will not give values equal to the specified value.

  • API Browser
  • JavaScript
  • URL
Copy
[number.lt( path, value )]
Copy
Prismic.Predicates.lt( path, value )
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bnumber.lt(%20path%2C%20value%20)%5D%5D%0A

Accepted values:

path

my.[custom-type].[number-field]

value

Number

Example:

  • API Browser
  • JavaScript
  • URL
Copy
[number.gt(my.product.price, 9.99)]
Copy
Prismic.Predicates.gt("my.product.price", 9.99)
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bnumber.gt(%20my.product.price%2C%209.99%20)%5D%5D

inRange

The number.inRange predicate checks that the value in the path is within the two values passed into the predicate.

This is an inclusive search, it will include values equal to the upper and lower limits.

  • API Browser
  • JavaScript
  • URL
Copy
[number.inRange( path, lowerLimit, upperLimit )]
Copy
Prismic.Predicates.inRange( path, lowerLimit, upperLimit )
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bnumber.inRange(%20path%2C%20lowerLimit%2C%20upperLimit%20)%5D%5D

Accepted values:

path

my.[custom-type].[number-field]

lowerLimit

Number

upperLimit

Number

Example:

  • API Browser
  • JavaScript
  • URL
Copy
[number.inRange(my.product.price, 10, 100)]
Copy
Prismic.Predicates.inRange(my.product.price, 10, 100)
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bnumber.inRange(my.product.price%2C%2010%2C%20100)%5D%5D

Date predicates

Prismic has sixteen predicates for dates and times.

All date predicates

The "after" and "before" predicates will not include a date or time equal to the given value. The "between" predicates will include dates and times equal to the given values.

  • API Browser
  • JavaScript
Copy
// Checks that the path's date is after a given date
[date.after( path, date )]

// Checks that a the path's date in the path is before a given date
[date.before( path, date )]

// Checks that the path's date is between two values
[date.between( path, startDate, endDate )]

// Checks that the path's day of the month is equal to the given day of the month
[date.day-of-month( path, day )]

// Checks that the path's day of the month is after the given day of the month
[date.day-of-month-after( path, day )]

// Checks that the path's day of the month is before the given day of the month
[date.day-of-month-before( path, day )]

// Checks that the path's weekday is equal to the given weekday
[date.day-of-week( path, weekday )]

// Checks that the path's weekday is after the given weekday
[date.day-of-week-after( path, weekday )]

// Checks that the path's weekday is before the given weekday
[date.day-of-week-before( path, weekday )]

// Checks that the path's month is equal to the given month
[date.month( path, month )]

// Checks that the path's month is after the given month
[date.month-after( path, month )]

// Checks that the path's month is before the given month
[date.month-before( path, month )]

// Checks that the path's year is equal to the given year
[date.year( path, year )]

// Checks that the path's hour is equal to the given hour
[date.hour( path, hour )]

// Checks that the path's hour is after the given hour
[date.hour-after( path, hour )]

// Checks that the path's hour is before the given hour
[date.hour-before( path, hour )]
Copy
// Checks that the path's date is after a given date
Prismic.Predicates.dateAfter( path, date )

// Checks that a the path's date in the path is before a given date
Prismic.Predicate.dateBefore( path, date )

// Checks that the path's date is between two values
Prismic.Predicates.dateBetween( path, startDate, endDate )

// Checks that the path's day of the month is equal to the given day of the month
Prismic.Predicate.dayOfMonth( path, day )

// Checks that the path's day of the month is after the given day of the month
Prismic.Predicate.dayOfMonthAfter( path, day )

// Checks that the path's day of the month is before the given day of the month
Prismic.Predicates.dayOfMonthBefore( path, day )

// Checks that the path's weekday is equal to the given weekday
Prismic.Predicates.dayOfWeek( path, weekday )

// Checks that the path's weekday is after the given weekday
Prismic.Predicates.dayOfWeekAfter( path, weekday )

// Checks that the path's weekday is before the given weekday
Prismic.Predicates.dayOfWeekBefore( path, weekday )]

// Checks that the path's month is equal to the given month
Prismic.Predicates.month( path, month )

// Checks that the path's month is after the given month
Prismic.Predicates.monthAfter( path, month )

// Checks that the path's month is before the given month
Prismic.Predicates.monthBefore( path, month )

// Checks that the path's year is equal to the given year
Prismic.Predicates.year( path, year )

// Checks that the path's hour is equal to the given hour
Prismic.Predicates.hour( path, hour )

// Checks that the path's hour is after the given hour
Prismic.Predicates.hourAfter( path, hour )

// Checks that the path's hour is before the given hour
Prismic.Predicates.hourBefore( path, hour )

Accepted values:

path

document.first_publication_date

document.last_publication_date

my.[custom-type].[date-field]

my.[custom-type].[timestamp-field]

date
startDate
endDate

ISO 8601 Standard date: "2002-08-28"

ISO 8601 Standard timestamp: "2002-08-28T15:30:00+0300"

13-digit Epoch: 1030545000000

day

Day of month

weekday

Day of week, starting with Monday. Will also accept first-letter capitalized ("Monday") and all-caps ("MONDAY").

'monday', 'mon', or 1
'tuesday', 'tue', or 2
'wednesday', 'wed', or 3
'thursday', 'thu', or 4
'friday', 'fri', or 5
'saturday', 'sat', or 6
'sunday', 'sun', or 7
month

Month, starting "january" or 1. Will also accept first-letter capitalized ("January") and all-caps ("JANUARY").

'january', 'jan', or 1
'february', 'feb', or 2
'march', 'mar', or 3
'april', 'apr', or 4
'may' or 5
'june', 'jun', or 6
'july', 'jul', or 7
'august', 'aug', or 8
'september', 'sep', or 9
'october', 'oct', or 10
'november', 'nov', or 11
'december', 'dec', or 12
year

Year

hour

An hour as a number, between 0 and 23. Date field values have an hour value of 0.

Here are some examples of how to use and combine date predicates:

A specific date

Use the at predicate:

  • API Browser
  • JavaScript
  • URL
Copy
[at(my.article.example_date, "2017-01-22")]
Copy
Prismic.Predicates.at("my.article.example_date", "2017-01-22")
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5B%5Bat(my.article.example_date%2C%20%222017-01-22%22)%5D%5D

By month and year

Combine the month and year predicates. This query will return content published in May 2017:

  • API Browser
  • JavaScript
  • URL
Copy
[date.year(my.article.example_date, 2017)]
[date.month(my.article.example_date, "May")]


Copy
[
  Prismic.Predicates.year("my.article.example_date", 2017),
  Prismic.Predicates.month("my.article.example_date", "May")
]
Copy
https://your-repo-name.cdn.prismic.io/api/v2/documents/search?ref=WmdIBCcAAHhUDe_K&q=%5Bdate.year(my.article.example_date%2C%202017)%5D%0A%5Bdate.month(my.article.example_date%2C%20%22May%22)%5D



Predicate Paths

Most predicates accept a path to denote the field being examined. The paths can take two formats, based on the predicate: 'document.[meta-value]' or 'my.[custom-type].[field]'.

my.[custom-type].[field]

This path allows you to query a specific field in a Custom Type. [custom-type] should be the API ID of a Custom Type, such as "blog_post". [field] should be the API ID of a field in that Custom Type, such as "author".

document.type

The API ID of a document's Custom Type.

document.id

The automatically-assigned document ID, which looks like this: WGvVEDIAAAcuB3lJ

document.tags

The tags assigned to a document. Tags must always be listed in an array.

document.first_publication_date

The date and time that the document was first published. This value never changes.

document.last_publication_date

The date and time that the document was last published. This value is updated every time new edits are published.

document

This path is only used with the fulltext predicate. It allows you to search all Rich Text, Title, Key Text, Select, and UID fields in a document.

Query Options

Query options are formatted as name=value, where the name representing the name of the option. The value is encoded. You can encode it yourself with JavaScript's built-in encodeURIComponent() function or with a web service.

All of the query methods provided by the JavaScript-based development kits will accept an options object as an argument, like so:

Copy
client.getByUID("blog_post", "hello-world", { fetchLinks: "author.name" })

This documentation is meant as a reference for the Rest API, but syntax for the JavaScript development kits is included for comparison. For more information on using query options with our JavaScript kits, see the documentation for @prismicio/client or our technology guides.

orderings

This option specifies what field to order your results by, and whether to order them ascending or descending.

Specify the field with the path my.[custom-type].[field]:

  • Unencoded
  • Encoded
  • JavaScript
Copy
orderings=[my.product.price]
Copy
orderings=%5Bmy.product.price%5D
Copy
{ orderings: "[my.product.price]" }

By default, the results will be ordered lowest to highest. To order results highest to lowest, add a space and desc:

  • Unencoded
  • Encoded
  • JavaScript
Copy
orderings=[my.product.price desc]
Copy
orderings=%5Bmy.product.price%20desc%5D
Copy
{ orderings: "[my.product.price desc]" }

To order by multiple fields, use a comma-separated list. The results will be ordered by the first path. When value of the first path is the same for multiple results, they will be ordered by the second path, and so on.

In this example, products will be sorted by price. Products with the same price will then be sorted by title.

  • Unencoded
  • Encoded
  • JavaScript
Copy
orderings=[my.product.price,my.product.title]
Copy
orderings=%5Bmy.product.price%2Cmy.product.title%5D
Copy
{ orderings: "[my.product.price,my.product.title]" }

Documents also have a first_publication_date and last_publication_date. These can also be used with orderings:

  • Unencoded
  • Encoded
  • JavaScript
Copy
orderings=[document.first_publication_date]
Copy
orderings=%5Bdocument.first_publication_date%5D
Copy
{ orderings: "[document.first_publication_date]" }

after

This option works with orderings to return documents after the one specified.

For example, imagine if you have a query that returns the following document IDs (in this order):

Copy
V9Zt3icAAAl8Uzob
PqZtvCcAALuRUzmO
VkRmhykAAFA6PoBj
V4Fs8rDbAAH9Pfow
G8ZtxQhAALuSix6R
Ww9yuAvdAhl87wh6

If you add the after option with the a value of "VkRmhykAAFA6PoBj", like this,

  • Unencoded
  • Encoded
  • JavaScript
Copy
after=VkRmhykAAFA6PoBj
Copy
after=VkRmhykAAFA6PoBj
Copy
{ after: "VkRmhykAAFA6PoBj" }

your query will return:

Copy
V4Fs8rDbAAH9Pfow
G8ZtxQhAALuSix6R
Ww9yuAvdAhl87wh6

By reversing the orderings in your query, you can use this same method to retrieve all the documents before the specified document.

graphQuery

GraphQuery is an advanced query option that enables selective fetching and deep fetching. See the section on GraphQuery below.

fetch

Please note: fetch is deprecated in favor of graphQuery.

This option is used to make queries faster by only retrieving the specified field(s).

To retrieve a single field, specify it with [custom-type].[field]:

  • Unencoded
  • Encoded
  • JavaScript
Copy
fetch=product.title
Copy
fetch=product.title
Copy
{ fetch: "product.title" }

To retrieve multiple fields, use array syntax:

  • Unencoded
  • Encoded
  • JavaScript
Copy
fetch=[product.title,product.description]
Copy
fetch=%5Bproduct.title%2Cproduct.description%5D
Copy
{ fetch: "[product.title, product.description]" }

fetchLinks

This option allows you to retrieve a specific content field from a linked document and add it to the document response object.

fetchLinks can not retrieve the following fields:

  • Embed
  • GeoPoint
  • Link
  • Link to Media
  • Rich Text (anything other than the first element)
  • Any field in a Group or Slice

To retrieve the linked content, use the format [linked-document-type].[field-on-linked-doc]:

  • Unencoded
  • Encoded
  • JavaScript
Copy
fetchlinks=author.name
Copy
fetchlinks=author.name
Copy
{ fetchLinks: "author.name" }

To retrieve multiple fields, use array syntax:

  • Unencoded
  • Encoded
  • JavaScript
Copy
fetchlinks=[author.name,author.avatar]
Copy
fetchLinks=%5Bauthor.name%2Cauthor.avatar%5D
Copy
{ fetchLinks: "[author.name,author.avatar]" }

lang

This option allows you to specify what locale you would like to retrieve content from. By default, the API will return content from your master locale.

To specify a particular locale, pass the locale code:

  • Unencoded
  • Encoded
  • JavaScript
Copy
lang=en-us
Copy
lang=en-us
Copy
{ lang: "en-us" }

To retrieve all locales, pass the wildcard value *:

  • Unencoded
  • Encoded
  • JavaScript
Copy
lang=*
Copy
lang=*
Copy
{ lang: "*" }

pageSize

This option defines the maximum number of documents that the API will return for your query. It accepts a number. The default is 20, and the maximum is 100.

  • Unencoded
  • Encoded
  • JavaScript
Copy
pageSize=100
Copy
pageSize=100
Copy
{ pageSize: 100 }

page

The page option defines the pagination for the result of your query. It defaults to 1, corresponding to the first page.

  • Unencoded
  • Encoded
  • JavaScript
Copy
page=2
Copy
page=2
Copy
{ page: 2 }

GraphQuery

GraphQuery is a query option that enables you to make for advanced queries. It allows for selective fetching (only retrieving specific fields) and deep fetching (retrieving content from linked documents and content relationships).

GraphQuery vs GraphQL

GraphQuery uses a syntax similar to GraphQL, and offers many of the same benefits. However, GraphQuery is not GraphQL, and it has no support for many GraphQL features, such as named queries or introspection. All GraphQuery features are described here.

Similar to the other query parameters, the format for GraphQuery is graphQuery=value. The value is an encoded GraphQuery string. You can encode the string with JavaScript's built-in encodeURIComponent() function or with a web service.

To help explain GraphQuery, we will use a concrete example of a blog. We will query a Custom Type called "post", which has some basic content: a Content Relationship for the author, a repeating Group for an image gallery, and a Slice for quotes. The author is another Custom Type, with a name, a photo, and a bio.

  • Unencoded
  • Encoded
  • JavaScript
Copy
graphQuery={post{title}}
Copy
graphQuery=%7Bpost%7Btitle%7D%7D
Copy
{ graphQuery: `{post{title}}` }
Copy
Post
- title (key text)
- main_image (image)
- description (rich text)
- linked_author (content relationship)
- repeating_group (group)
  - image (image)
  - caption (key text)
- slicezone
  - quote_slice
    - non-repeatable
      - quotation (rich text)
    - repeatable
      - icon (image)

Author
- name (key text)
- photo (image)
- bio (rich text)

Selective Fetching

To select a single field, specify the custom type and then the field:

Copy
{
  post {
    title
  }
}

To select multiple fields, add more fields:

Copy
{
  post {
    title
    description
  }
}

To retrieve a field in a group, use the name of the group and then the field:

Copy
{
  post {
    repeating_group {
      image
      caption
    }
  }
}

To retrieve a field in a slice, access the body section of your custom type, then use ...on slice_name to access a specific slice, and then non-repeat and repeat to access to the non-repeatable and repeatable sections of the slice.

Copy
{
  post {
    body {
      ...on quote_slice {
        non-repeat {
          quotation
        }
        repeat {
          icon
        }
      }
    }
  }
}

To query all fields in a document, a group, or a slice, use fragment syntax by writing ... followed by the name of the custom type, field, or slice section, and then Fields. In the following example, we're performing a GraphQuery operation on both the post custom type and the author custom type.

Copy
{
  post {
    repeating_group {
      ...repeating_groupFields
    }
    body {
      ...on quote_slice {
        repeat {
          ...repeatFields
        }
      }
    }
  }
  author {
    ...authorFields
  }
}

Deep Fetching

Deep fetching allows you to fetch content from a Content Relationship or Link field.

To access content from linked documents, we use the union type, ...on. With the union type, you can specify the custom type you want to access. The API will return the data from all documents of that custom type linked to your document.

Copy
{
  post {
    linked_author {
      ...on author {
        name
      }
    }
  }
}

You can combine deep fetching syntax with the fragment syntax to access all fields of a document plus content from linked documents.


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.