Introduction to the Content API endpoint

Prismic provides an API endpoint to retrieve your content as a JSON response.

Why should you use a kit?

Using one of the official Prismic development kits is the easiest way to have all current and upcoming features of Prismic automatically! Look at all the technologies and frameworks we have available.

The Prismic API provides different powerful features for developers and publishers, Scheduling & Previews, Multi-language support, and more.

These features are possible through a ref token mechanism required in the API. It specifies the needed content version (draft, master, etc.). The development kits manage this by default. They pass the necessary ref automatically so that you don't have to do it manually.

The API endpoint

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


The search endpoint takes the following essential parameters:


string (required)

The reference for the required content version. For example: master, preview, release preview.


string (required, if the repository is private)

The secure token for accessing the API.


A list of predicates

The required query.

Find more parameters for pagination, language and orderings in the search parameter reference.

The Tags API

The tags API endpoint /api/tags allows you to return all the tags from your repository in an array. Read the full reference for the Tags API.

Prismic API Ref

The API ref specifies the content version you'd like to query. 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.

Why do I need to use refs?

The API ref specifies which version of your content you want to query from the repository. The ref will change if you query published documents using the master, a preview of a particular draft, or a release using the corresponding preview ref.

How do I get my master ref?

You can retrieve the master ref in the JSON response of the /api CDN endpoint. Here an example URL of an API search endpoint where you'll see an object with the ref:


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


Or you can see this info by visiting the API browser at:


Discover how to get the ref for a preview release in the beyond the API section.

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

Yes. but all /api calls are fast, small, and scalable. Moreover, calling the /api endpoint allows you to determine whether things have changed since last time. This way you can always be confident about using the cached version of your queries, allowing for efficient caching and instantaneous refresh of cache whenever there are changes.

The Access Token

If you've set your repository to private, then you'll need to provide an access token to retrieve your content. To do this you will need to use the access_token parameter and provide your token.


Refer to this guide to learn how to generate an access token for your repository.

The query parameter

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


Querying with predicates

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

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

A given predicate has three parts:

assertion( pathToField, value)

Here are the predicates that Prismic 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(, ["id1", "id2"])

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


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


Checks whether a fragment has a value


Checks if a fragment doesn't have a value


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


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 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 query will look like the following.

  page: 1
  results_per_page: 20
  results_size: 20
  total_results_size: 39
  total_pages: 2
  prev_page: null
  results: [{
    id: "WPeD0SoAACsABzNC"
    uid: "prismic-from-scratch-with-nodejs"
    type: "page-nodejs"
    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.

Pagination of API Results

When querying a Prismic repository, your results will be paginated. By default, there are 20 documents per page in the results. You can read more about how to manipulate the pagination in the Pagination for Results page.

The /api endpoint

As described above every Prismic repository has a /api endpoint.


This endpoint provides you with all the pieces of information needed to build your queries. This includes: the current master ref, a list of your custom types, tags, languages, etc.

Here is what a typical response for your /api endpoint will look like.

  "refs": [{
    "id": "master",
    "ref": "W2xL2CsAAHbechvf",
    "label": "Master",
    "isMasterRef": true
  "bookmarks": {},
  "types": {
    "blog": "Blog Posts",
    "page": "Pages",
  "languages": [{
    "id": "en-gb",
    "name": "English - Great Britain"
    "id": "fr-fr",
    "name": "French - France"
  "tags": [],
  "forms": {
    "everything": {}
  "oauth_initiate": "",
  "oauth_token": "",
  "version": "1c97b53",
  "license": "This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit",
  "experiments": {
    "draft": [],
    "running": []

Why does Prismic use this method?

The Prismic API is a standard RESTful API. IT works the same way as standard websites. You have a unique and single URL endpoint representing the API "homepage", in Prismic, it is the /api endpoint.

When you query /api, the response tells you what actions you can do from there. This is done by returning links and forms. Forms contain all the information you need to submit your actions (URL, queries or parameters)

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

The API browser

Every Prismic repository provides an API browser that allows you to test your queries and see the results. You can directly access your API browser at the URL Here you can enter your predicates and switch the API reference to test what results you will receive. You will need to activate the access to another ref through the settings in API & Security.

How the Prismic API Browser works

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

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.