Fetch Content

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.

You can choose from one of the following visibility levels:

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:

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.

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:

• A Quote slice containing a quote text field.
• A Text slice containing a text rich text field.

{
  "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,
  }}
/>

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.

• getFirst()
• getByID()
• getByUID()
• getSingle()

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.

• get()
• getByIDs()
• getByUIDs()
• getByType()
• getByTag()
• getByEveryTag()
• getBySomeTags()

Paginated responses are in this format:

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.

• getAllByIDs()
• getAllByUIDs()
• getAllByType()
• getAllByTag()
• getAllByEveryTag()
• getAllBySomeTags()

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"

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.

Errors

Query methods may throw the following errors:

• NotFoundError: A matching page was not found.
• ForbiddenError: An incorrect access token was provided.
• ParsingError: The filters 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.

You can see current and past API usage by navigating to your repository’s Settings > Usage Dashboard.

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.

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.