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.
To retrieve your content, you will have to query your Prismic repository's GraphQL endpoint URL. The GraphQL API is accessible at:
https://your-repo-name.cdn.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.
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.
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.
You can retrieve the master ref by hitting the API CDN endpoint and seeing the JSON response.
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.
https://your-repo-name.cdn.prismic.io/api/v2The response you retrieve from the endpoint above will include more information, but the important part will be the following:
{
"refs":[
{
"id":"master",
"ref":"WTga3CAAAG1yMSot",
"label":"Master",
"isMasterRef":true
}
]
}Or you can see this info by visiting the API browser at:
https://your-repo-name.prismic.io/api/v2As 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:
{
"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.
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.
Authorization: Token YOUR-TOKENRefer to this guide to learn how to generate an access token for your repository.
Important to know: contrary to a classic GraphQL API, you need to use a GET request to query the Prismic GraphQl API.
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.
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
id
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
tags
Array of String
The list of tags in the document
alternateLanguages
Array of Documents
The list of all translations of this document
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.
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:
landing_page(uid:"powered-by-prismic", lang:"en-us"){
title
subtitle
}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:
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.
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:
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":
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.
Was this article helpful?
Can't find what you're looking for? Get in touch with us on our Community Forum.