The Prismic API

On this page, you'll learn what an API is and how the Prismic API works.


Prismic comprises three technologies:

  • A content management system
  • An application called Slice Machine
  • An API

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.

First, let’s break down the parts of Prismic:

  • A content management system is software for handling text and images
  • Slice Machine is a tool for developers to create building blocks for the website builder
  • An API is a way of transferring data

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.

A headless website builder is a bit magical because it beams the content into your website application very efficiently. How does the content from a headless CMS get into the website? Via an API.

On this page, we'll explain what an API is and how the Prismic API works.

This is a beginner-friendly introduction

This article offers a general understanding of the Prismic API. If you want to dive straight into developing with the Prismic API, we recommend the Technology Guides or — for advanced use cases — the Document API Technical Reference.

How APIs work

API is an acronym for "Application Programming Interface." Basically, an API is a bridge between two computers or programs. On the web, "API" often refers specifically to networks of computers in warehouses that store information for websites.

When talking about web APIs, we often refer to a "client" and a "server." The client is the computer performing a request, and the server is the computer fulfilling the request. Often, the client sends a request for data (like, "What's the weather?") and the server responds with an answer ("Currently warm and sunny"). But the client might also ask the server to do something (like, "Add milk to my grocery list"), and the server could respond with a status ("Done").

Example: Reading the News

Imagine you're browsing your favorite news website. You type "politics" into the search bar and hit "enter." The web page says to the API, "Hey! Retrieve all the results with the word 'politics.'" The server returns those API results and the web page updates with the search results.

What is HTTP?

HTTP is the foundation of the web. It's the standard protocol for requesting documents on the internet. It's also a popular protocol for sending and receiving API requests. In fact, when you type a URL into your browser's address bar and hit "enter," that's an HTTP API request. HTTP stands for "Hypertext Transfer Protocol." Web pages are written in HTML, which stands for "Hypertext Markup Language."

Every HTTP request includes a method to declare what kind of request it is (like when you call a friend and start the conversation by saying either "I have some news," "I need a favor," or "I have a question"). The most popular methods are GET (to request a resource), POST (to create a resource), PATCH (to update a resource), and DELETE (to delete a resource).

Every HTTP request also includes a URL, which is the address for the resource. The URL includes the domain (like "google.com"), but it can also have a lot more information. For example, this is a URL for the Pokemon API. The URL includes the domain, the API endpoint, and parameters specifying that the client would like four Pokemon starting from the twentieth.

Today, most HTTP requests are sent as HTTPS, which is an encrypted HTTP request. The "S" is for "secure."

Copy
https://pokeapi.co/api/v2/pokemon?limit=4&offset=20

What is an API endpoint?

An endpoint is one part of a web API. Specifically, it is a URL that points to a server where a client can send HTTP requests. When an endpoint receives an API request, it runs a program to process the request and take action, depending on the HTTP method, and either create, read, update, or delete a resource on the server.

What is a Rest API?

Rest (typically written "REST," but we choose to title-case it) is a specific set of guidelines for creators of HTTP APIs. Rest standardizes the structure of the request and the response.

Most (but not all) of the Prismic APIs are Rest APIs. The only one that is not a Rest API is the GraphQL API, which is — as the title states — a GraphQL API (more on that later).

What is JSON?

Rest APIs can return information in many formats, but the most common is JSON, which is the format that the Prismic API uses.

JSON (which stands for "JavaScript Object Notation") is derived from the JavaScript programming language, but today it is language-agnostic and one of the most popular formats for sending and receiving data. JSON is notable for being relatively easy to read. Here's an example of valid JSON data:

Copy
{
  "name": "Stuart",
  "age": 9,
  "student": true,
  "pets": [
    "Sophie the Dog",
    "Arnold the Lizard",
    "Chirpy the Bird"
  ]
}

As you can see, you don't need to be a computer (or a computer nerd) to read or write JSON.

Developers can write programs to use this data:

Copy
Welcome! {name} is {age} years old.

Which would output text like this:

Copy
Welcome! Stuart is 9 years old.

The six Prismic API endpoints

As explained above, Prismic delivers content via an API. Prismic has six API endpoints:

Entry API

Read-only

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

Document API

Read-only

https://your-repo-name.cdn.prismic.io/api/v2/documents/search

Tag API

Read-only

https://your-repo-name.cdn.prismic.io/api/tags

GraphQL API

Read-only

https://your-repo-name.cdn.prismic.io/graphql

Custom Type API

Read/write

https://your-repo-name.cdn.prismic.io/customtypes

Integration Fields Write API

Write-only

https://if-api.prismic.io/if/write/your-repo-name--catalog-name

The most important endpoints are the Entry API and the Document API. They work together to deliver most Prismic content.

Refs and the Entry API

The Prismic API is fast. Really fast. It has to be. It processes 20,000,000,000 requests each month, powering thousands of websites. One of the reasons the API is so fast is because it uses a system of refs and caching.

When a client requests a document from Prismic, the Prismic API checks the database for a document matching the description. It responds with what it finds. On average, that request-response cycle takes 250ms.

But what if the Prismic API has received the same request before?

A woman standing at a bus stop
An API query is kind of like waiting for a bus. Photo by Johen Redman / Unsplash.

Let's use a metaphor. Imagine you're standing near a bus stop, and someone asks you when the next bus is coming. You pull out the timetable, check the times, and give them an answer. All in, it might take you a minute. But what if someone else comes along and asks the same question. You can give them an answer immediately because you already know.

Eventually, the bus will come and go. If a third person comes and asks when the next bus is coming, you'll need to check the timetable again.

The Prismic API works similarly. If the API receives a request it has already received, it sends back the same data. In that case, the request-response cycle takes a fraction of the time: 50ms.

How does the API know if it can send back the same data? Using refs. 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.

Here's a diagram of the whole process:

A diagram of the Prismic API
How a basic Prismic API query works.

So, where does the ref come from? The Entry API.

The Entry API is basically the gateway to your repository. When you query the Entry API, you get back some basic information about your repository, including the ref for the current version of your content, called the "master ref."

The Entry API endpoint is located at:

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

(Replace your-repo-name with your repository's name.)

You can put the Entry API endpoint into your web browser's address bar. After you hit "enter", you should see something like this:

A screenshot of the Entry API endpoint in a browser.
JSON from the Entry 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:

A screenshot of the Entry API endpoint in a browser.
JSON from the Entry API endpoint with formatting.

There's a lot of information here. But the most important property is the first one, the refs property. You must use the master ref to query your current content from the Document API.

Use Prismic's development kits for real-world API queries

This article provides a theoretical overview of how the Prismic API works. However, we don't recommend performing requests to the Prismic API manually in your app. We have official and community kits for building and sending API requests. We recommend using these kits. Learn more in the Technologies section.

Predicates and the Document API

Prismic has two APIs to query content: the Document API, which uses Rest, and the GraphQL API. We'll discuss the GraphQL API later. For now, we'll query content from the Document API.

A basic query to the Document API looks like this:

Copy
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 predicates. Predicates are query filters.

Prismic has 29 predicates:

  • 7 predicates for filtering logically
  • 3 predicates for filtering numerically
  • 17 predicates for filtering by date
  • 1 predicate for filtering by similarity
  • 1 predicate for filtering by location

The logical predicate at is the most commonly-used predicate. It searches for a matching value. So, to search for the blog post with the unique ID (UID) of "hello-world", you would use this predicate:

Copy
[at(my.blog_post.uid,"hello-world")]

Predicates 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 predicates and how to use them in the Predicate Reference.

You can test your predicates in Prismic's API Browser. To get to the API Browser, use the Entry API endpoint for your repository, but remove the .cdn segment, like so:

Copy
https://your-repo-name.prismic.io/api/v2

In the API Browser, you can construct queries with predicates. 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.

The Prismic API Browser.
Constructing a query in the Prismic API browser.

You can also add options to your API query. To learn more, see the Query Options 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 Entry API, the ref, and much more.

Tags and the Tag API

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:

Copy
https://your-repo-name.cdn.prismic.io/api/tags

This endpoint only returns a list of tags.

Selective fetching and the GraphQL API

GraphQL APIs are a popular alternative to Rest APIs. GraphQL APIs allow for more advanced and programmatic API requests. Every Prismic repository has a GraphQL endpoint alongside the Rest Document API endpoint:

Copy
https://your-repo-name.cdn.prismic.io/graphql

When you send a GET request to a Rest API, you generally receive an entire document as a response. It's like ordering a set menu at a restaurant. When you send a request to a GraphQL API, you ask for each specific data point — like ordering items à la carte.

One big advantage of GraphQL is that you always know what you will get. With a set menu, you don't necessarily know what's coming unless you've eaten at this restaurant before. Even then, the menu might change without warning. When you order à la carte, you know exactly what will be on your plate. For developers, this helps reduce bugs and improve performance.

You can construct your own GraphQL queries and see what the response looks like in the GraphQL Explorer:

Copy
https://your-repo-name.prismic.io/graphql

But, be warned! GraphQL is an advanced technology, and the syntax can be quite confusing.

Third-party data and the Integration Fields API

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 Fields API comes in.

Your developer can send data from a third-party service to the Integration Fields 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.

Web development with the Custom Type API

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. So, 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 in order 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.

Does Prismic have a Write API?

An API that lets you modify resources on the server is called a write API. Prismic does not have a write API to edit the content of a Prismic repository. This is a deliberate product decision. Write APIs introduce security and stability issues.

We believe that many of the features enabled by a write API — such as editing content models or integrating third-party data — could be better served by more specific features, and we've used that philosophy to guide our product development. That's why we have the Integration Fields Write API and the Custom Types API, as described above.

If you have a use case for a write API, we'd love to hear from you. Please drop us a line on the forum to tell us what you're thinking.

There is a way to programmatically edit resources on the Prismic server. That is with our Import/Export feature, which is not an API. Import/Export allows you to create and edit documents in bulk. This is very technical work, so we recommend that a developer take care of this.

How to build with the Prismic API

For more information on how to build with Prismic, visit the documentation for your web development framework:


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.