The Rest API Browser

Every Prismic repository includes an API Browser to help you discover your API, test your queries, and display the JSON results. This is based on our RESTFUL API. Here we will go through the details on how to use the API Browser.

To learn how to use the Prismic API with your chosen technology, see our technologies guides:

To learn more about the Rest API itself, see our API documentation:

Go to the browser

Here is the url for your repository's API Browser:

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

Select a ref

When using the API Browser, you must first select the ref for the query. The ref select box will allow you to select any present or future release which is accessible.

Note that if you're supposed to have access to future releases and you can't see them, you may have to log in. To do that, click on the lock icon in the upper-right corner and this will ask for your credentials to reveal the future release refs.

Unlocking the Release refs in the API Browser

Choose your form

The form by default is "Everything", which retrieves and allows you to query all your content.

The other available forms are collections that you define in the settings of your repository. A collection allows you to limit the documents to specific tags or Custom Types.

In the example below we have a collection for each programming language in our documentation. When you select a collection, this will predefine a predicate to filter the results.

Selecting a Collection in the Prismic API Browser

Enter your predicates to query the form

Enter your predicates in the form named "Query." Type out the predicate and press enter to set it. If you need to modify a predicate, simply double-click on it and you will be able to make changes.

To learn more about the specifics of each predicate, check out our Predicates reference page.

Adding a Predicate in the Prismic API Browser

Enter your orderings to sort the results

Enter your sorting options in the "Orderings" form. After you've written the ordering, press enter to set it. After that, double-click on the ordering if you need to modify it.

To learn more about how to write the orderings, check out the Order your results page.

Adding an Orderings option in the Prismic API Browser

Change the result format (HTML or JSON)

The API Browser will provide styled HTML results by default, but you can switch to browsable JSON results. To do this you can click on the HTML / JSON switch at the top of your API Browser.

Switching between HTML and JSON in the Prismic API Browser

Refine your query as needed

Launch your query to see what results are retrieved. If your query wasn't exactly what you were looking for, reopen the query form and change your query. Then repeat the process as needed!

Raw API response

Once you're satisfied with how your queries are defined, you may wish to have the direct JSON formatted response from the API. In that case you can include 'cdn' to your endpoint address and get the direct API response.

Copy
http://your-repository-name.cdn.prismic.io/api/v2/documents/search?ref=MASTER_REF&q=Your_Predicates

Filter results with query parameters

When Querying the API Browser, you can add query parameters after the “ref” parameter and before the hashtag (#) in the URL to get filtered results based upon the parameters described in the Search parameter Reference.

For instance, if the API Browser URL is:

Copy
http://your-repository-name.cdn.prismic.io/api/v2/documents/search?ref=MASTER_REF#format=json 

Then, to get a page with only one result, add the pageSize parameter:

Copy
http://your-repository-name.cdn.prismic.io/api/v2/documents/search?ref=MASTER_REF&pageSize=1#format=json

And if there is a need to add more than one query parameter, it can be done by adding ‘&’ before each query parameter. for example, getting 2 results (parameter : page size=2) and starting from page 3 (parameter : page=3):

Copy
http://your-repository-name.cdn.prismic.io/api/v2/documents/search?ref=MASTER_REF&pageSize=2&page=3#format=json

Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.