Contentful Getting Started: Quickstart Guide & First API Call (2026)

Getting started overview

To begin using Contentful, developers typically follow a sequence of steps that involve setting up an account, configuring a content space, and obtaining the necessary API credentials. Contentful operates as a headless Content Management System (CMS), meaning it focuses on content storage and delivery via APIs, rather than generating a frontend. This approach allows content to be published to various digital channels, such as websites, mobile applications, and IoT devices, from a single source (Contentful developer documentation).

The core components for a quick start include:

1. Account Creation: Registering for a Contentful account.
2. Space Setup: Creating a "Space," which acts as a container for all content, assets, and content models.
3. Content Model Definition: Structuring content types (e.g., "Blog Post," "Product") with fields (e.g., "Title," "Body," "Image").
4. Content Entry: Populating the defined content types with actual data.
5. API Key Generation: Creating API keys to access content programmatically.
6. First API Request: Retrieving content using the Content Delivery API (CDA) or Content Preview API (CPA).

The Content Delivery API (CDA) is designed for retrieving published content in production environments, while the Content Management API (CMA) is used for programmatic content creation, updates, and deletion (Contentful Content Delivery API reference). This guide focuses on retrieving content using the CDA.

Here's a quick reference table outlining the initial steps:

Create an account and get keys

To start, navigate to the Contentful signup page and register for a new account. Contentful offers a free Community plan that provides sufficient resources for development and testing, including up to 5 users, 1 environment, and 25,000 records (Contentful pricing details).

Once your account is created and you are logged into the Contentful web app, follow these steps:

1. Create a Space: From the dashboard, click "Create a new Space." You can choose to start with an example space or an empty one. For this guide, an empty space is recommended to build from scratch. Give your space a descriptive name.
2. Define a Content Model:
   • In your new space, go to the "Content model" section in the left navigation.
   • Click "Add content type."
   • Name your content type (e.g., "Product" or "BlogPost") and give it an optional description. Click "Create."
   • Add fields to your content type. For example, for a "BlogPost," you might add a "Text" field for the title, a "Rich text" field for the body, and a "Media" field for a featured image. Ensure you click "Create and configure" for each field and set appropriate validation rules if necessary.
   • After adding all desired fields, click "Save" on the content type editor.
3. Add Content Entries:
   • Navigate to the "Content" section.
   • Click "Add entry" and select the content type you just created (e.g., "BlogPost").
   • Fill in the fields with some sample data.
   • Click "Publish" to make the content available via the Content Delivery API.
4. Generate API Keys:
   • Go to "Settings" > "API keys" in the left navigation.
   • Click "Add API key."
   • Contentful automatically generates a new API key set, including a Space ID and a Content Delivery API - Access Token. These are the credentials you will use to fetch content.
   • Note down both the Space ID and the Content Delivery API - Access Token. These are sensitive credentials and should be treated securely, similar to how API keys for services like Stripe or Twilio are handled (Stripe API Keys documentation, Twilio API Keys guide).

Your first request

Once you have your Space ID and Content Delivery API - Access Token, you can make your first API request. This example uses a simple HTTP GET request to fetch all entries of a specific content type. Replace YOUR_SPACE_ID and YOUR_CDA_ACCESS_TOKEN with your actual credentials, and YOUR_CONTENT_TYPE_ID with the ID of the content type you created (e.g., blogPost or product). The content type ID is typically the camelCase version of your content type name.

The base URL for the Content Delivery API is https://cdn.contentful.com.

Using curl (command line):

curl -X GET \
  'https://cdn.contentful.com/spaces/YOUR_SPACE_ID/environments/master/entries?content_type=YOUR_CONTENT_TYPE_ID' \
  -H 'Authorization: Bearer YOUR_CDA_ACCESS_TOKEN'

Using JavaScript (Node.js with node-fetch):

const fetch = require('node-fetch'); // npm install node-fetch

const SPACE_ID = 'YOUR_SPACE_ID';
const CDA_ACCESS_TOKEN = 'YOUR_CDA_ACCESS_TOKEN';
const CONTENT_TYPE_ID = 'YOUR_CONTENT_TYPE_ID';

async function fetchContent() {
  try {
    const response = await fetch(
      `https://cdn.contentful.com/spaces/${SPACE_ID}/environments/master/entries?content_type=${CONTENT_TYPE_ID}`,
      {
        headers: {
          Authorization: `Bearer ${CDA_ACCESS_TOKEN}`,
        },
      }
    );

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log(JSON.stringify(data, null, 2));
  } catch (error) {
    console.error('Error fetching content:', error);
  }
}

fetchContent();

The response will be a JSON object containing an array of entries that match your content type, along with metadata. Contentful's JSON response format is detailed in their Content Delivery API documentation for querying entries.

Common next steps

After successfully retrieving your first content entry, several common next steps can enhance your Contentful integration:

1. Explore Contentful SDKs: Contentful provides SDKs for various languages, including JavaScript, Python, Ruby, PHP, Java, .NET, iOS, and Android. Using an SDK can simplify API interactions by handling authentication, request formatting, and response parsing (Contentful SDK documentation).
2. Implement GraphQL: For more complex data fetching requirements or to reduce over-fetching, consider using Contentful's GraphQL API. It allows you to request only the specific data fields you need (Contentful GraphQL API reference).
3. Integrate with a Frontend Framework: Connect Contentful to a frontend framework like React, Vue, or Next.js to build dynamic web applications. Many tutorials are available demonstrating such integrations.
4. Utilize the Content Management API (CMA): If your application requires programmatic content creation, updates, or deletions, you will need to use the CMA. This API requires a different type of access token with write permissions (Contentful Content Management API reference).
5. Webhooks: Set up webhooks to trigger actions in your application whenever content is published, updated, or deleted in Contentful. This enables real-time synchronization and automated workflows (Contentful Webhooks documentation).
6. Asset Management: Learn how to upload and manage digital assets (images, videos, documents) within Contentful and retrieve them via the API.
7. Localization: If you plan to deliver content in multiple languages, explore Contentful's localization features to manage translated content effectively.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Check API Keys: Double-check that your Space ID and Content Delivery API - Access Token are correct and have not been mistyped. API tokens are case-sensitive.
• Content Type ID: Ensure the content_type parameter in your request URL exactly matches the ID of your content type in Contentful. Content type IDs are typically camelCase versions of the content type name (e.g., "Blog Post" becomes blogPost). You can find the exact ID in the Contentful web app under "Content model" by clicking on your content type.
• Content Published: Verify that the content entries you expect to retrieve have been published. Only published content is available through the Content Delivery API. Draft content requires the Content Preview API (CPA).
• Network Issues: Confirm that your development environment has internet connectivity and is not blocked by a firewall from accessing cdn.contentful.com.
• Error Messages: Pay close attention to the error messages returned by the API. Common errors include 401 Unauthorized (incorrect API token), 404 Not Found (incorrect Space ID or content type ID), or 403 Forbidden (permissions issue). Contentful's API documentation provides details on API error codes and their meanings.
• Environment: Ensure you are querying the correct environment, typically master, unless you have configured custom environments. The URL structure /environments/master/ is standard.
• CORS Issues: If you are making requests directly from a web browser (e.g., in a frontend application), you might encounter Cross-Origin Resource Sharing (CORS) errors. Contentful's CDA supports CORS, but ensure your browser environment is configured correctly. For server-side applications, CORS is generally not an issue.

If problems persist, consult the Contentful troubleshooting documentation for more specific guidance or reach out to Contentful support.