Introduction to the Content Query API

prismic.io provides an API query browser to retrieve your content as a JSON response. This section explains in more depth the API structure and main concepts. We strongly recommend using our development kits and libraries provided. They are available for most major programming language and frameworks.

Why should you use a kit?

Using one of the official prismic.io development kits is the easiest way to automatically have all current and upcoming features of prismic.io!

The prismic.io API provides different powerful features for developers and publishers, including draft previews, release previews, A/B testing, an efficient caching mechanism, and more.

These features are made possible through a simple ref token mechanism that is required in the API. The ref token given to the API will specify the needed content version (draft, A/B variation, master, etc). The development kits manage this by default by passing the necessary ref automatically so that you don't have implement it manually.

The API search endpoint

The search endpoint allows you to query your content and get a JSON response. Here is the URL of search endpoint:

Copy
http://your-repository-name.prismic.io/api/v2/documents/search

The search endpoint takes the following essential parameters:

ref

String

A string representing the required content version (master, preview, release preview, A/B variation, etc)

token

string

The secure token for accessing the API (only needed if your repository is set to private)

q

A list of predicates

The required query

More parameters for pagination, language, etc. are available in the complete parameters reference.

Prismic API Ref

The API ref is required to specify the content version/branch you'd like to query. For public content, you will use the master ref.

Why do I need to use refs?

The API ref provides a powerful mechanism for specifying what you want to query. You can choose to query public documents using the master ref. You can also choose to query a preview of a particular draft, or a release using the corresponding preview ref.

The A/B testing feature also makes a good use of the ref parameter for querying the needed variation for a given viewer.

How do I get my master ref?

You can retrieve the master ref using the /api endpoint.

As mentioned above, to query published versions of documents, you need to specify the master ref. The master ref changes every time you publish changes. Whenever you do a search query, you need to pass along the most recent master ref. You can get the latest master ref by querying the /api endpoint.

Copy
http://your-repository-name.prismic.io/api/v2

The response you retrieve from the endpoint above will include more information, but the important part will be the following:

Copy
{
"refs":[
    {
      "id":"master",
      "ref":"WTga3CAAAG1yMSot",
      "label":"Master",
      "isMasterRef":true
    }
  ]
}

Discover how to get the ref for a preview release or an A/B test in the beyond the API section.

Do I need to make an extra call when I query my content?

Yes. You might be concerned about the extra call needed to retrieve the API ref, but the /api call is optimised to be very fast, small, and scalable.

Moreover, calling the /api endpoint allows you to determine whether things have changes since last time. This way you can always be confident about using cached version of your queries, allowing for very efficient caching and instantaneous refresh of cache whenever changes are made.

The query parameter

The q parameter allows you to send your query as a list of predicates:

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

Querying with predicates

The prismic.io API use predicates to query the content. Predicates might seems complex at a first glance but it is much easier than it seems. Predicates provide a very powerful mechanism to compose and express your query using a single endpoint.

Your query would read like the following: Give me all the document that satisfy [predicate1, predicate2, ... ]

A given predicate is composed of three parts:

assertion( pathToField, value)

Here are the predicates that prismic.io api provides.

at(path, value)

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

not(path, value)

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

any(path, [value1, value2])

Checks whether the fragment matches any of the values in the array

in(document.id, ["id1", "id2"])

Used specifically to retrieve an array of documents by their IDs or UIDs

fulltext

Helps you check if a string is anywhere inside a document or inside a specific field

has

Checks whether a fragment has a value

missing

Checks if a fragment doesn't have a value

similar

Takes the ID of a document and returns a list of documents with similar content

near

Checks that the value in the path is within the radius of the given coordinates

A set of number predicates

Less than, greater than, or in a range

There are a few predicates that are specifically used for the Number field like checking if a value in the number fields is less or greater than a value

A set of Date & Time based predicated

dateAfter, dateBefore, dateBetween, dayOfMonth, dayOfMonthAfter, dayOfMonthBefore, etc.

The prismic.io API provide a set of dates predicates to query content based on date, range of date, etc.

You can discover the complete predicates reference here.

The API response

The API response for a prismic.io query will look like the following.

Copy
{
	page: 1
	results_per_page: 20
	results_size: 20
	total_results_size: 39
	total_pages: 2
	next_page: http://prismicio-docs.prismic.io/api/documents/search?ref=WTbNGykAAIIsblz1&q=%5B%5Bat%28document.type%2C+%22page-nodejs%22%29%5D%5D&page=2&pageSize=20
	prev_page: null
	results: [
		{
		id: "WPeD0SoAACsABzNC"
		uid: "prismic-from-scratch-with-nodejs"
		type: "page-nodejs"
		href: http://prismicio-docs.prismic.io/api/documents/search?ref=WTbNGykAAIIsblz1&q=%5B%5B%3Ad+%3D+at%28document.id%2C+%22WPeD0SoAACsABzNC%22%29+%5D%5D
		tags: [ ]
		first_publication_date: "2017-04-19T15:59:34+0000"
		last_publication_date: "2017-05-26T15:49:11+0000"
		+ … -slugs: []
		+ … -linked_documents: []
		+ … -data: {}
		}
	]
	version: "32fa92a"
}

This response will include the number of document returned by the API, the number of pages of results, and the data of the documents.

Why does prismic.io use this method?

prismic.io API is a standard RESTful API. A true RESTful api works the same way as standard websites. You have a unique and single URL endpoint that represents the API "homepage", in prismic.io it is the /api endpoint.

By querying /api, the response tells you what kind of action can be done from there. This is done by returning links and forms. Forms contain all the information you need to submit your actions (URL, query, parameters, etc)

A true RESTful API improves discoverability and allows flexibility in changing urls and parameter names. Explaining how a true RESTful API works is beyond the purpose of this section.

Predicates use a very standard and powerful query mechanism called datalog. The concept of datalog allows combining predicates to express your queries.

The API browser

Every prismic.io repository provides an API browser that allows you test your queries and see the results. You can directly access your API browser at the url http://your -repository-name.prismic.io/api. Here you can enter your predicates and switch the reference of the api to test what results you will receive. You will need to activate the access to other ref through the settings in API & Security.

You can discover more about this on the API Browser page.