Introduction to the Prismic GraphQL API

In order to retrieve the content from your repository, you will need to query the repository API. When you create your query you will specify exactly what it is you are looking for. You could query the repository for all the documents of certain type or retrieve the one specific document you need.

Let's take a look at how to put together queries for whatever case you need.

The GraphQL endpoint

To retrieve your content, you will have to query your Prismic repository's GraphQL endpoint URL. The GraphQL API is accessible at:

https://your-repository.prismic.io/graphql

We recommend that you use a GraphQL client like Apollo or Relay, but you can also query the API directly through curl. The GraphQL endpoint takes the following essential headers:

Prismic-Ref

String

A string representing the required content version (master, preview, etc.)

Authorization

String

The secure token for

Good news if you're using Apollo

We handle this for you if you are using the Apollo Link library. It will automatically get the master ref and pass in the headers of the request.

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.

How do I get my master ref?

You can retrieve the master ref by hitting the api endpoint.

Copy

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

As mentioned above, in order 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 query, you need to pass along the most recent master ref. You can get the latest master ref by querying the api endpoint.

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
    }
  ]
}

You'll find the ref you need to pass in the "ref" attribute.

Good news if you're using Apollo

As mentioned above, this is handled for you if you are using the Apollo Link library. It will automatically get the master ref and pass in the headers of the request.

The Access Token

If you've set your repository to private, then you'll need to provide an access token in order to retrieve your content. To do this you will need to use the Authorization: Token header and provide your token.

Copy

Authorization: Token YOUR-TOKEN

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

How to query with the GraphQL API

A GraphQL API that uses GET

Important to know: contrary to a classic GraphQL API, you need to use a GET request to query the Prismic GraphQl API.

A basic Query structure

The basic structure of a GraphQL query to Prismic will determine the fields that you retrieve from a specific custom type.

Ask for what you want

As the Official GraphQL Documentation puts it: "At its simplest, GraphQL is about asking for specific fields on objects."

For every document provided by the Prismic GraphQL API, all fields from the custom type are on the first level and all the Meta Data (ID, UID, publication dates, etc.) is in the _meta object.

Copy

landing_page(uid:"powered-by-prismic", lang:"en-us"){
  title
  subtitle
  _meta{
    id
    firstPublicationDate
  }
}

Here is the list of the Meta Data that you can find for each document:

type

String

The custom type of the document

String

The id of the document

uid

String

The UID / slug value for your document (if the type has a UID field)

firstPublicationDate

DateTime

The first publication date of the document

lastPublicationDate

DateTime

The last publication date (update) of the document

Predefined Query Fields (Predefined Queries)

For every Custom Type in your Prismic repository, the GraphQL API has two predefined query fields -- one to query a single document and another one to query a set of documents of that type. For either option you need to specify which fields you want to retrieve and a set of arguments to filters the results.

Query for a single document

To query one particular document of a given type, you have a predefined query field that you will pass as a selector. You will need to pass the uid of your document as well as its lang.

For example, if you want to get the title and the subtitle of the landing page that has the UID value of "powered-by-prismic" you will use the following request:

Copy

landing_page(uid:"powered-by-prismic", lang:"en-us"){
  title
  subtitle
}

Query for multiple documents

The GraphQL also provides a predefined query field to get all documents of a given custom type. For example, if you want to query all Landing Pages from your repo, the query allLanding_pages can be used.

Here is an example that will get the title and the subtitle of all your Landing Pages:

Copy

allLanding_pages{
  edges{
    node{
      title
      subtitle
    }
  }
}

GraphQL Autocomplete

You can find all available queries in your API Explorer by using the autocomplete with CTRL+SPACE.

Filtering Documents

On queries that return multiple results you can use different arguments to filter the documents that are returned. These options are separated into two main places:

First-level arguments which are filters on Meta information of the documents (ID, UID, publication dates, etc.)
The where argument lets you filter on content fields in your custom type (title, subtitle, etc.)

Here is an example of a query that that filers on the Meta information lang:

Copy

query{
  allLanding_pages(lang:"en-us"){
    edges{
      node{
        title
        subtitle
      }
    }
  }
}

And here is a simple example that shows how to use the where argument to filter based on a content field. In this case we are filtering based on a field with the API ID "is_featured":

Copy

query{
  allLanding_pages(where:{is_featured:"true"}){
    edges{
      node{
        title
        subtitle
      }
    }
  }
}

You can find more details on how to filter entries in the Basics on how to query the API page.

We also give you more control over your queries by allowing you to order, filter, and paginate the results. You can find more details on these in the Query The API Section of the Documentation.