Contentful

This is for:

Developer System Administrator

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.

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.

Contentful integration diagram | Coveo

1

The Coveo GraphQL API source retrieves content using the Contentful GraphQL Content API. If you don’t need to index item-level permissions, you can also use a Coveo Sitemap source or Coveo Web source.

2

The Coveo Atomic search interface sends requests to the Coveo Search API. The Search API returns relevant results to the interface. Another way to query the Coveo index is through an MCP client and Coveo MCP Server connection. See AI assistants and agents for more information.

3

The Coveo Atomic search interface sends usage analytics to the Coveo Platform, where it can support machine learning models that improve relevance.

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.

  1. On the Sources (platform-ca | platform-eu | platform-au) page, click Add source.

  2. In the Add a source of content panel, select the Cloud (cloud-icon) tab.

  3. 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" 1
      },
      "Endpoints": [
        {
          "paging": {
            "offsetType": "item",
            "pageSize": 25,
            "TotalCountKey": "data.barcaHelpCollection.total"
          },
          "Path": "content/v1/spaces/<CONTENTFUL_SPACE_ID>", 2
          "Method": "GET",
          "ItemPath": "data.barcaHelpCollection.items",
          "SkippableErrorCodes": "404",
          "ItemType": "Article",
          "Body": "%[body]",
          "Uri": "https://help.barca.group/article/%[cat_slug]", 3
          "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" 4
        }
      ]
     }
  ]
}
1 The @ApiKey placeholder automatically uses the API key value you entered in the Authentication section without exposing it in clear text.
2 Replace <CONTENTFUL_SPACE_ID> with your actual Contentful space ID.
3 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.
4 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.

  1. Click Add query.

  2. Name your query (for example, @MyQuery).

    The GraphQL query field references your query by its name.

  3. 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.

    Tip

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

    Example query in Contentful GraphQL Explorer

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

  1. Confirm that Coveo Atomic is the right approach for the Contentful search experience by following Choose the right approach.

  2. If applicable, follow Atomic getting started documentation to start building the Coveo Atomic search interface.

    Tip

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

Considerations

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.

What’s next?