Search parameter reference for the REST API

Here you will find a complete reference about the various search parameters available when creating queries with the prismic.io REST API.

Adding a search parameter to the query url

In order to use any of these parameters, you will need to append them to the query url. For example, let's say that this is the query url for all the documents in your repository.

Copy
https://repo-name.prismic.io/api/v2/documents/search?ref=WUfdIigAACgAe7f9

Then to set the pageSize parameter to 40, for example, we would add &pageSize=40 it to the url as follows.

Copy
https://repo-name.prismic.io/api/v2/documents/search?ref=WUfdIigAACgAe7f9&pageSize=40

You can add as many parameters as you need for your query. Here's an example where we add pageSize=10 and page=3 to the query url.

Copy
https://repo-name.prismic.io/api/v2/documents/search?ref=WUfdIigAACgAe7f9&pageSize=10&page=3

Now we will go through and describe all the available query parameters.


after

The after parameter can be used along with the orderings option. It will remove all the documents except for those after the specified document in the list.

To clarify, let’s say you have a query that return the following documents in this order:

V9Zt3icAAAl8Uzob (Page 1)
PqZtvCcAALuRUzmO (Page 2)
VkRmhykAAFA6PoBj (Page 3)
V4Fs8rDbAAH9Pfow (Page 4)
G8ZtxQhAALuSix6R (Page 5)
Ww9yuAvdAhl87wh6 (Page 6)

If you add the after parameter and specify the document-ID for page 3, “VkRmhykAAFA6PoBj”, your query will return the following:

V4Fs8rDbAAH9Pfow (Page 4)
G8ZtxQhAALuSix6R (Page 5)
Ww9yuAvdAhl87wh6 (Page 6)

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

The value you enter for the after parameter needs to take the following format.

Copy
after={document-id}

{document-id}

string

The document ID of the target document

Example:

Copy
after=VkRmhykAAFA6PoBj


fetch

The fetch parameter is used to make queries faster by only retrieving the specified field(s).

The value you enter for the fetch parameter needs to take the following format.

Copy
fetch={custom-type}.{field}

{custom-type}

The custom type API-ID of the linked document

{field}

The API-ID of the field you wish to retrieve from the linked document

To retrieve a single field, simply specify the field as shown below.

Copy
fetch=product.title

To retrieve more than one field, you just need to comma separate all the fields you wish included in the response.

Copy
fetch=product.title,product.price


The fetchLinks parameter allows you to retrieve a specific content field from a linked document and add it to the document response object.

Note that this will only retrieve content of the following field types:

  • Color
  • Content Relationship
  • Date
  • Image
  • Key Text
  • Number
  • Rich Text (but only returns the first element)
  • Select
  • Timestamp
  • Title

It is not possible to retrieve the following content field types:

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

The value you enter for the fetchLinks option needs to take the following format:

Copy
fetchLinks={custom-type}.{field}

{custom-type}

The custom type API-ID of the linked document

{field}

The API-ID of the field you wish to retrieve from the linked document

To view a complete example of how this option works, view the example on the Fetch Linked Document Fields page.

Examples:

Copy
fetchLinks=author.full_name
fetchLinks=author.first-name,author.last-name


lang

The lang option defines the language code for the results of your query.

Specify a particular language/region

You can use the lang option to specify a particular language/region you wish to query by. You just need to set the lang value to the desired language code, for example "en-us" for American English.

If no lang option is provided, then the query will default to the master language of the repository.

Copy
lang=en-us

Query all languages

You can also use the lang option to specify that you want to query documents in all available languages. Simply set the lang option to the wildcard value *.

Copy
lang=*


orderings

The orderings parameter orders the results by the specified field(s). You can specify as many fields as you want.

lowest to highest

It will automatically order the field from lowest to highest

highest to lowest

Use "desc" next to the field name to instead order it from greatest to lowest

Copy
orderings=[my.product.price] // lowest to highest
orderings=[my.product.price desc] // highest to lowest

Multiple orderings

You can specify more than one field to order your results by. To do so, simply add more than one field in the array.

The results will be ordered by the first field in the array. If any of the results have the same value for that initial sort, they will then be sorted by the next specified field.

Here is an example that first sorts the products by price from lowest to highest. If any of the products have the same price, then they will be sorted by their titles.

Copy
orderings=[my.product.price,my.product.title]

Sort by publication date

It is also possible to order documents by their first or last publication dates.

first_publication_date

The date that the document was originally published for the first time

last_publication_date

The most recent date that the document has been published after editing

Copy
orderings=[document.first_publication_date]
orderings=[document.last_publication_date]


page

The page parameter defines the pagination for the result of your query.

If you do not include this parameter, the pagination will default to "1", corresponding to the first page.

value

integer

page index

Example:

Copy
page=2


pageSize

The pageSize parameter defines the maximum number of documents that the API will return for your query.

The default is 20, and the max is 100.

value

integer

page size (between 1 and 100)

Example:

Copy
pageSize=20