Fetch Content
Read content from your Prismic repository.
The Content API is used to read content from your Prismic repository. The API supports common features, like filtering, sorting, and pagination. Content is served as JSON and works directly with Prismic’s SDKs.
@prismicio/client
is the official client for the Content API.
How to fetch content
Use @prismicio/client
and its query methods to fetch content. Responses are automatically typed with TypeScript, ensuring safe data access.
Each website framework has a specific way of using the Prismic client. Visit the Next.js, Nuxt, or SvelteKit guide to learn how to set up the client for your framework.
Once set up, the client can be used to fetch page content. The following example fetches a page with the UID about-us
.
import { createClient } from "@/prismicio";
export default async function Page() {
const client = createClient();
// Fetch the "about-us" page
const page = await client.getByUID("page", "about-us");
}
Content visibility
All published content is publicly accessible through the API by default.
To limit or expand access, navigate to the repository’s Settings > API & Security page and adjust the API access setting.
The API & Security settings in a Prismic repository.
You can choose from one of the following visibility levels:
Published content | Content in a release | Archived content | |
---|---|---|---|
Open API | Public | Public | No access |
Public API for Master only (default) | Public | Requires access token | No access |
Private API | Requires access token | Requires access token | No access |
For maximum security, use Private API to authenticate all requests with an access token. You’ll need to generate an access token in your repository’s settings and configure your client to use it.
See the Next.js, Nuxt, or SvelteKit guide for step-by-step instructions on generating a token and configuring your client.
Response format
API responses are returned as JSON. The following sections describe how pages, fields, and slices are formatted.
Pages
Pages are returned as objects with metadata. The data
property contains the page’s fields.
{
"id": "YCiUyRUAACQAxfZK",
"uid": "my-first-post",
"url": "/blog/my-first-post",
"type": "blog_post",
"href": "https://example-prismic-repo.cdn.prismic.io/api/v2/...",
"tags": ["Tag 1", "Tag 2"],
"first_publication_date": "2021-02-14T03:22:26+0000",
"last_publication_date": "2022-07-09T00:36:18+0000",
"slugs": ["my-first-post"],
"linked_documents": [],
"lang": "en-us",
"alternate_languages": [],
"data": {
// ...
}
}
Pages contain these properties:
id
string
uid
string | null
The page’s user-provided identifier. Only present if the page type has a UID field.
type
string
data
object
first_publication_date
string
The page’s first publication date in ISO 8601 format.
last_publication_date
string
The page’s last publication date in ISO 8601 format.
alternate_languages
object[]
The page’s alternate language versions.
lang
string
tags
string[]
href
string
slugs
string[]
The page’s slugs. The first slug is the current slug.
linked_documents
object[]
Fields
Each page’s fields are stored in its data property as individual properties.
The format of each field differs depending on the field’s type. See the documentation for each specific field type to see its API format.
See all of the available fields
The following example page has two fields:
title
: A rich text field.author
: A content relationship field.
{
"id": "YCiUyRUAACQAxfZK",
// ...
"data": {
"title": [
{
"type": "heading1",
"text": "Build a website that grows",
"spans": []
}
],
"author": {
"id": "XxnD3REAACYAk_CJ",
"type": "author",
"tags": [],
"slug": "ada-lovelace",
"lang": "en-us",
"uid": "ada-lovelace",
"data": {
"name": [
{
"type": "paragraph",
"text": "Ada Lovelace",
"spans": []
}
]
}
}
}
}
Each field can be read by accessing its property:
const title = page.data.title;
const author = page.data.author;
const authorName = author.data?.name;
Fields are fully typed using TypeScript.
Slices
Slices are made up of fields and are the primary location for a page’s content. Slices are provided in a page’s slices
property within the data
object, alongside the page’s non-slice fields.
The following example page has two slices:
{
"id": "YCiUyRUAACQAxfZK",
// ...
"data": {
"slices": [
{
"id": "quote$e568fae3-e996-43c2-af06-dbf42b215cc2",
"slice_type": "quote",
"variation": "default",
"version": "initial",
"primary": {
"quote": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
},
"items": []
},
{
"id": "text$afba88d2-3ce4-46b5-b42b-b89e8dcd6dc5",
"slice_type": "text",
"variation": "default",
"version": "initial",
"primary": {
"text": [
{
"type": "heading1",
"text": "Build a website that grows",
"spans": []
}
]
},
"items": []
}
]
}
}
The slices
property can be passed directly to the <SliceZone>
component from Prismic’s SDKs.
<SliceZone
slices={page.data.slices}
components={{
quote: QuoteSlice,
text: TextSlice,
}}
/>
Learn more about displaying slices
Query methods
@prismicio/client
provides many methods that fetch content. The methods can be grouped into the following categories:
get
methods (single): Return a single matching page.get
methods (paginated): Return paginated responses with up to 100 pages per response.getAll
methods: Return all matching pages. May make multiple network requests.
get
methods (single)
These methods return a single matching page.
If a matching page cannot be found, the client throws a NotFoundError
.
These methods are useful when you need to display a page’s contents, like on a blog post’s page template.
get
methods (paginated)
These methods return multiple matching pages in a paginated object. Each response can contain up to 100 pages.
Paginated responses are in this format:
results
PrismicDocument[]
A paginated list of pages matching the query.
page
number
The current page number.
total_pages
number
The total number of pages.
results_size
number
The number of results in the page of results.
results_per_page
number
The maximum number of results per page.
total_results_size
number
The total number of results within all pages.
next_page
string | null
The API URL to the next page, if one exists.
prev_page
string | null
The API URL to the previous page, if one exists.
You can fetch a specific paginated set of pages using the page
and pageSize
options:
import { createClient } from "@/prismicio";
export default async function Page() {
const client = createClient();
const blogPosts = await client.getByType("blog_post", {
page: 2,
pageSize: 10,
});
}
These methods are useful when you only need to display some pages, like showing 10 blog posts at a time.
getAll
methods
These methods return all matching pages in a single array. The client may make multiple network requests to fetch all matching pages.
These methods are useful when needing a complete list of pages, like when statically building your website. If you do not need all matching pages at once, use the paginated get
methods instead for better performance.
Sort
Use the orderings
option to sort results. It accepts an array of objects, in order of priority, each containing a field name and its sorting direction.
This example fetches all blog posts sorted by the published_on
field in descending order, using the first_publication_date
metadata as a fallback.
import { createClient } from "@/prismicio";
export default async function Page() {
const client = createClient();
const blogPosts = await client.getAllByType("blog_post", {
orderings: [
{ field: "my.blog_post.published_on", direction: "desc" },
{ field: "document.first_publication_date", direction: "desc" },
],
});
}
The field
property must be in one of the following formats:
"my.[page-type].[field]"
"document.[metadata]"
The direction
property can be one of the following:
"asc"
(default)"desc"
Learn more about the orderings
option
Filter
Use the filters
option to filter results. It accepts an array of filters constructed using the client’s filter
helpers.
This example fetches all blog posts published after 2028-03-07
.
import { filter } from "@prismicio/client";
import { createClient } from "@/prismicio";
export default async function Page() {
const client = createClient();
const blogPosts = await client.getAllByType("blog_post", {
filters: [filter.dateAfter("my.blog_post.published_on", "2028-03-07")],
});
}
The client’s collection of filter
helpers works with text, dates, numbers, and more.
See the full list of filters
Errors
Query methods may throw the following errors:
NotFoundError
: A matching page was not found.ForbiddenError
: An incorrect access token was provided.ParsingError
: Thefilters
option contains invalid syntax.PreviewTokenExpiredError
: The preview token expired.RefExpiredError
: The client is using an expired content version.RefNotFoundError
: The client is using an invalid content version.RepositoryNotFoundError
: The Prismic repository does not exist.PrismicError
: A generic error thrown when something unexpected is returned.
You can detect these errors using instanceof
. This example shows how to handle a NotFoundError
:
import { notFound } from "next/navigation";
import { NotFoundError } from "@prismicio/client";
import { createClient } from "@/prismicio";
export default async function Page() {
const client = createClient();
const page = await client.getByUID("page", "about-us").catch(handleError);
}
function handleError(error: unknown) {
if (error instanceof NotFoundError) notFound();
throw error;
}
Previews
Draft content can be fetched during a full-website preview, allowing writers to review content before publishing.
@prismicio/client
supports fetching draft content using the following methods:
resolvePreviewURL()
: Returns a page’s URL based on a preview session’s ref and page ID. This is necessary to redirect to a previewed page’s URL.queryContentFromRef()
: Configures the client to fetch content from a specific ref. This is necessary to fetch content from the preview ref.
Each framework has a specific setup needed to support previews. With the setup, previews work automatically, seamlessly switching between performant published content and private draft content.
API limits
The Content API’s limits are based on your Prismic repository’s plan.
Plan | API Calls | Bandwidth |
---|---|---|
Free | 4 million calls/month | 100 GB (no overages) |
Starter | 4 million calls/month | 100 GB (paid overages up to 500 GB) |
Small | 4 million calls/month | 100 GB (paid overages up to 500 GB) |
Medium | 5 million calls/month | 500 GB (paid overages up to 1 TB) |
Platinum | 10 million calls/month (paid overages up to 20 million) | 1TB (paid overages up to 5 TB) |
Enterprise | Custom | Custom |
You can see current and past API usage by navigating to your repository’s Settings > Usage Dashboard.
The Usage Dashboard showcasing Content API usage.
Rate limits
The API has a protective rate limit of 200 non-cached requests per second per repository to ensure consistent performance for all users.
The client automatically retries requests that have been blocked by the rate limit.
API Explorer
The API Explorer is an in-browser app for building and running client queries.
It’s useful for inspecting your repository’s content, testing queries, and learning how different filters and parameters behave.
The API Explorer running a query.
There are two ways to access the API Explorer:
- From your repository: Visit the Settings > API & Security page and click API Explorer
- From prismic.io: Visit https://prismic.io/explorer
Visiting the API Explorer from your repository provides better parameter suggestions, such as inferring content model and field types when building filters.
HTTP API reference
A low-level HTTP API reference for the Content API is provided to help debug and provide insight into the client’s implementation.
See the Content API reference