Contentful

This is for:

In this article

About Contentful
Why use Coveo with Contentful?
Considerations
Recommended integration architecture
Prerequisites
Integrate Contentful and Coveo
What’s next?

You can integrate Contentful with Coveo to index selected entries and metadata through the Contentful GraphQL Content API and make the content available in a Coveo-powered search experience.

About Contentful

Contentful is a headless content management system that manages structured content and exposes it through APIs.

Why use Coveo with Contentful?

Make selected Contentful content discoverable alongside content from other systems without changing the Contentful authoring workflow.

Index the items and metadata that are relevant to your users.
Once indexed, surface this content alongside content from your other sources. Present it in a single Coveo-powered search interface with filtering, ranking, and personalized results, or make it available to an LLM app or agent through a Coveo MCP Server connection.

Considerations

The recommended integration described below assumes that you don’t need to index item-level access permissions. The provided JSON configuration example doesn’t apply access permissions to the indexed items. To replicate item-level permissions in Coveo, see GraphQL API source permission configuration.

The recommended integration uses a Coveo Atomic search interface to surface the indexed content. Before you build it, confirm that Atomic is the right approach for your experience. Another way to surface the indexed content is through an MCP client and Coveo MCP Server connection. See AI assistants and agents for more information.

Recommended integration architecture

A Coveo GraphQL API source sends requests to the Contentful GraphQL Content API and indexes the returned entries and metadata in the Coveo Platform. A Coveo Atomic search interface can present the indexed Contentful content on a Contentful-powered website and send usage analytics to the Coveo Platform.

The following diagram shows the recommended Contentful integration components and their interactions.

The Coveo GraphQL API source retrieves content using the Contentful GraphQL Content API.

The Coveo Atomic search interface sends requests, including usage analytics data, to the Coveo Search API. The Search API returns relevant results to the interface.

The Coveo Search API records the search interface’s usage analytics in Coveo Analytics, where the data can support machine learning models that improve relevance. Search interface result click events and AI-generated answers are also logged through other means and aren’t shown on the diagram.

Prerequisites

You have access to a Contentful space and environment that contain the entries you want to make searchable, as well as a Contentful API key that can read the selected content.
You have a tested GraphQL query that returns the selected entries, their metadata, a unique URL for each entry, and a field that indicates the last time an entry changed.
You have a license that allows you to create the required source in your Coveo organization.
Your Coveo organization hasn’t reached its source quota. You can review your quotas on the License & Usage (platform-ca | platform-eu | platform-au) page, along with your usage.
You have the privileges to create and manage sources.

Integrate Contentful and Coveo

Follow these steps to configure the Coveo GraphQL API source and verify the indexed content.

Step 1: Create a GraphQL API source

Follow the instructions below to add a GraphQL API source that uses the Cloud content retrieval method.

On the Sources (platform-ca | platform-eu | platform-au) page, click Add source.
In the Add a source of content panel, select the Cloud () tab.
Click the GraphQL API tile.

Step 2: Configure your source

Configure the Coveo GraphQL API source in the following sections: Authentication, Content to include, and GraphQL queries. The following instructions explain how to configure each section.

"Authentication" section

Enter your Contentful API Key in the API key box.

"Content to include" section

In the JSON configuration box, add the configuration that defines the call to perform against the Contentful GraphQL Content API endpoint and how Coveo will handle the response. See GraphQL API source configuration reference for details.

Example

The following configuration shows how the source could be configured to index article items from the https://help.barca.group demo site.

{
  "Services": [
    {
      "Url": "https://graphql.contentful.com",
      "Headers": {
        "Authorization": "Bearer @ApiKey" 
      },
      "Endpoints": [
        {
          "paging": {
            "offsetType": "item",
            "pageSize": 25,
            "TotalCountKey": "data.barcaHelpCollection.total"
          },
          "Path": "content/v1/spaces/<CONTENTFUL_SPACE_ID>", 
          "Method": "GET",
          "ItemPath": "data.barcaHelpCollection.items",
          "SkippableErrorCodes": "404",
          "ItemType": "Article",
          "Body": "%[body]",
          "Uri": "https://help.barca.group/article/%[cat_slug]", 
          "ClickableUri": "https://help.barca.group/article/%[cat_slug]",
          "Title": "%[title]",
          "ModifiedDate": "%[sys.publishedAt]",
          "Metadata": {
            "articletags": "%[tags[*]]",
            "cat_slug": "%[slug]",
            "ec_category": "%[ecCategory[*]]",
            "ec_description": "%[ecShortdesc]",
            "ec_shortdesc": "%[ecShortdesc]",
            "eng_blogimage": "%[engBlogimage.url]",
            "objecttype": "Article",
            "thumbnailurl": "%[engBlogimage.url]?w=240"
          },
          "PayloadJsonContent": "@MyQuery" 
        }
      ]
     }
  ]
}

	The `@ApiKey` placeholder automatically uses the API key value you entered in the Authentication section without exposing it in clear text.
	Replace `<CONTENTFUL_SPACE_ID>` with your actual Contentful space ID.
	Each Coveo indexed item must have a unique URL. Concatenating `https://help.barca.group/article/` with the `%[cat_slug]` dynamic value creates that unique URL.
	The `PayloadJsonContent` value must match the name of a GraphQL query defined in the GraphQL queries section.

"GraphQL queries" section

Configure the GraphQL query you want Coveo to execute to retrieve your content.

Click Add query.
Name your query (for example, @MyQuery).

The GraphQL query field references your query by its name.
In the GraphQL query field, enter your query. To ensure content freshness, include a date field that gets updated on an item modification so that the source picks up content changes in a timely manner.

To build and test your queries, use the GraphiQL App.

Step 3: Index your Contentful content

Build the source, then use the Content Browser (platform-ca | platform-eu | platform-au) to verify the indexed items.

Step 4: Create source mappings and fields

The JSON configuration extracts item metadata from the API response. Create the required source mappings and fields to index the metadata you want to use in search experiences.

Step 5: Build the search experience

Follow the Getting started with Atomic documentation to start building the Coveo Atomic search interface.

Create your search interface project using the npm create @coveo/ui command line tool.

What’s next?

See source update schedules to configure when your source checks for changed content.
See GraphQL API source permission configuration to index permissions for restricted Contentful content.
See Tune relevance to improve the results returned by the search experience.
See the integration directory for other Coveo integration opportunities.