The Prismic API
On this page, you will learn how the Prismic API works.
Learn how the Prismic API works.
Prismic comprises three technologies:
- A content management system (software for handling text and images)
- An application called Slice Machine (an application for building slices)
- An API (an access point for data)
These three technologies come together to form a powerful headless website-building platform.
In order to understand what a headless website builder is and how Prismic works, it helps to understand APIs and how the Prismic API works.
Traditional website builders use the same software to both store content and generate the website that displays the content. A headless website builder doesn’t generate the website. This is a popular approach because it can be more flexible, sustainable, maintainable, scalable, and performant.
So, if a headless website builder doesn’t generate the website, how does the content from a headless CMS get into the website? Via an API.
On this page, we’ll explain how the Prismic API works.
Prismic has six API endpoints:
| Repository API Read-only | |
| Document API Read-only | |
| Tag API Read-only | |
| Custom Type API Read/write |
|
Integration Field Write API Write-only | |
| Migration API Write-only |
|
The most important endpoints are the Repository API and the Document API. They work together to deliver most Prismic content.
Repository API: Fetch refs
The Repository API is the gateway to your repository. When you query the Repository API, you get back some basic information about your repository, including the ref for the current version of your content, called the “master ref.” A ref is an identifier for a specific version of your content, like draft, scheduled, or — most importantly — newest. Every time you publish changes, a new ref is generated.
Every request for content includes a ref that states what version of the content to send back. That way, if you request content twice with the same ref, the API knows it can reuse cached data. Even though you make two requests to the API, the result is, on average, many times faster than querying uncached content.
When you make changes to your content, Prismic may store older refs. This ensures that a ref will work even if content has been changed since the request was initiated. However, in general, you should always use the most recent ref, as old refs will get purged eventually.
Here’s a diagram of the whole process:
How a basic Prismic API query works.
The Repository API endpoint is located at:
https://your-repo-name.cdn.prismic.io/api/v2
(Replace your-repo-name with your repository’s name.)
You can put the Repository API endpoint into your web browser’s address bar. After you hit “enter”, you should see something like this:
JSON from the Repository API endpoint without formatting.
This is the raw JSON API response. It’s unformatted, meaning it doesn’t have any line breaks. You can install a browser extension to format it, like JSON Formatter for Chrome, JSON Peep for Safari, or JSONView for Firefox. Once formatted, the JSON should look more like this:
JSON from the Repository API endpoint with formatting.
Document API: Find and filter content
Prismic’s main API for reading data in the Document API. A basic query to the Document API looks like this:
https://prismicio-docs-v3.cdn.prismic.io/api/v2/documents/search?ref=Yj2uKBEAACIAOf9Q
Let’s break that down:
https | This is an HTTPS request |
prismicio-docs-v3 | This is the name of the repository we’re querying |
cdn | This specifies that we’re using the Prismic CDN, which is a special infrastructure to make queries faster |
prismic.io | This is the Prismic domain |
api/v2/documents/search | This is the Document API endpoint |
? | The question mark marks the beginning of our query |
ref=Yj2uKBEAACIAOf9Q | This is the ref that we’ll use to query content |
This query will return the 20 most recently changed documents from the API as JSON.
To get specific documents, you can use filters. Filters are a way to refine your query.
Prismic has 29 filters:
- 7 filters for filtering logically
- 3 filters for filtering numerically
- 17 filters for filtering by date
- 1 filter for filtering by similarity
- 1 filter for filtering by location
The logical filter at is the most commonly used. It searches for a matching value. To search for the blog post with the unique ID (UID) of “hello-world”, you would use this filter:
[at(my.blog_post.uid,"hello-world")]
Filters check every document and compare a specified property on that document against the provided value. If the document passes the comparison, the API will include the document in its results.
You can learn more about all of the filters and how to use them in the Filter Reference.
You can test your filters in Prismic’s API Browser. To get to the API Browser, use the Repository API endpoint for your repository, but remove the .cdn segment, like so:
https://your-repo-name.prismic.io/api/v2
In the API Browser, you can construct queries with filters. For instance, the following query will search for any documents in the Prismic documentation repository that are tagged as either “Nuxt.js” or “Next.js”, are not marked as “beta”, and have a meta titled defined.
Constructing a query in the Prismic API Browser.
Then you can sort your queries using orderings. For instance, the following query will search for all documents in the Prismic documentation repository and order them by the date and time they were first published.
Sorting a query in the Prismic API Browser.
To learn more about orderings and other options you can add to your API query, check out the Document API Technical Reference.
To make a query to the API, we strongly recommend using a development kit. The development kit will take care of the query to the Repository API, the ref, and much more.
Tag API: Read your tags
Prismic has a built-in tagging system. You can open any document in your repository, click on the tags bar at the top of the document, and type in a tag. You can use these tags to filter your documents in the document list.
If you need to fetch a list of all of the tags in your repository, you can query the Tag API endpoint:
https://your-repo-name.cdn.prismic.io/api/tags
This endpoint only returns a list of tags.
Integration Field API: Add third-party data
Most content in Prismic is authored in the Prismic interface. The Prismic interface is intuitive, stable, and secure. This helps ensure that any changes to content are safe. However, sometimes, you need to incorporate content from another source — like e-commerce items from a product catalog. That’s where the Integration Field API comes in.
Your developer can send data from a third-party service to the Integration Field API. If an Integration Field is included in your custom type, you can select data from the API to add to your document. With the API integration, your developer can keep the third-party data up-to-date without editing the document. This ensures that the API integration can’t corrupt information in your repository, since the third-party data is safely sandboxed.
Custom Type API: Create models
The Custom Types API is more advanced. Every document in Prismic belongs to a custom type. The custom type defines the structure of the content. A blog post has a different structure from a recipe or a sales page. You could have a “blog post” custom type, a “recipe” custom type, and a “sales page” custom type. Each one would have a different structure. Your developer needs to know this structure to build website pages that present this data. One way to see the structure is by viewing it in the Prismic interface. Another way to see (and edit) the structure is with the Custom Type API. This API allows for faster development workflows and advanced developer integrations. One such advanced integration is Slice Machine, our developer tool for building custom types.
Migration API: Create drafts
Prismic’s Migration API allows you to create and edit documents in your repository. However, those changes won’t immediately appear on your website. Instead, they will be staged in a “Migration Release” (which you can find from the “Migrations” tab of your repository). Changes will be saved in a draft state and must be published manually.
For more information on how to build with Prismic, visit the documentation for your web development framework: