Contentful API Getting Started: Quickstart Guide (2026)

Getting started overview

This guide outlines the essential steps to begin interacting with the Contentful API, focusing on initial setup and making a successful first request. Contentful provides two primary APIs: the Content Delivery API (CDA) for reading published content and the Content Management API (CMA) for creating, updating, and deleting content. Successful access requires an account, a Contentful space, and appropriate API keys.

The process typically involves:

1. Signing up for a Contentful account.
2. Creating a new space or using an existing one.
3. Generating API access tokens within that space.
4. Constructing and executing an API request using the obtained credentials.

Contentful offers SDKs for multiple programming languages, simplifying interaction with the API. For initial testing, direct HTTP requests using tools like cURL or a browser's developer console are also effective.

Here’s a quick reference table for the getting started steps:

Create an account and get keys

To begin, navigate to the Contentful sign-up page and create a new account. Contentful offers a free Community (Developer) tier, which is suitable for getting started and testing API functionalities.

Once registered and logged in, you will be prompted to create a new space or given access to a default one. A space in Contentful acts as a container for all your content, content models, and assets. Each space has a unique identifier, known as the Space ID, which is crucial for API requests.

Next, you need to generate an API key. Follow these steps within the Contentful web application:

1. From your space dashboard, go to Settings in the top navigation bar.
2. Select API Keys from the dropdown menu.
3. Click the Add API Key button.
4. Give your API key a descriptive name (e.g., "My First API Key").
5. The system will generate a new API key pair: a Space ID and a Content Delivery API - access token. The Content Delivery API (CDA) token is used for fetching published content. If you plan to manage content (create, update, delete), you will need to generate a Content Management API (CMA) token separately, which requires specific permissions.
6. Copy both the Space ID and the Content Delivery API - access token. These are your primary credentials for making read-only requests to the Contentful API. Keep them secure, as they grant access to your content.

Before making a request, ensure your space has some content. You can define a content model (e.g., a "Blog Post" with fields like "Title" and "Body") under the "Content model" section and then create and publish at least one entry under the "Content" section.

Your first request

With your Space ID and Content Delivery API access token, you can now make your first request. This example uses the Content Delivery API to fetch entries, which is a common initial use case. We'll demonstrate with cURL and a JavaScript example using the Contentful JavaScript SDK.

Using cURL (REST API)

The Content Delivery API endpoint for fetching entries follows the pattern https://cdn.contentful.com/spaces/{SPACE_ID}/environments/{ENVIRONMENT_ID}/entries. The default environment is master. Replace {SPACE_ID} and {CDA_ACCESS_TOKEN} with your actual credentials.

curl -X GET \
  'https://cdn.contentful.com/spaces/{YOUR_SPACE_ID}/environments/master/entries' \
  -H 'Authorization: Bearer {YOUR_CDA_ACCESS_TOKEN}'

This request fetches all entries in your specified space and environment. You can add query parameters to filter or narrow down results. For instance, to fetch entries of a specific content type, add ?content_type={CONTENT_TYPE_ID} to the URL.

A successful response will return a JSON object containing an array of entries and associated metadata. If you receive an error, double-check your Space ID, access token, and ensure you have published content in your space.

Using JavaScript SDK

Contentful provides a JavaScript SDK that simplifies API interactions. First, install the SDK:

npm install contentful

Then, create a client and fetch entries:

const contentful = require('contentful');

const client = contentful.createClient({
  space: '{YOUR_SPACE_ID}',
  accessToken: '{YOUR_CDA_ACCESS_TOKEN}'
});

client.getEntries()
  .then((response) => {
    console.log(response.items);
  })
  .catch(console.error);

This code initializes the Contentful client with your credentials and then calls getEntries() to fetch all content entries. The response will be an object containing items (your content entries) and other metadata.

Common next steps

After successfully retrieving your first content, consider these common next steps to further integrate with Contentful:

• Content Modeling: Define more complex content models with various field types (e.g., rich text, references, assets) to structure your data effectively. Contentful's flexible content modeling is a core feature, as detailed in their content modeling guide.
• Querying and Filtering: Explore the Content Delivery API's extensive query parameters to filter, sort, and paginate content, retrieving only the data you need.
• Asset Management: Upload and manage digital assets (images, videos, documents) and link them to your content entries. The Content Delivery API for assets allows fetching these files.
• Webhooks: Set up webhooks to trigger external processes (e.g., rebuilding a static site, sending notifications) whenever content is published, updated, or deleted. This enables automated workflows and continuous delivery, as described in Contentful's webhook documentation. For general webhook security practices, Twilio's webhook security guide offers relevant insights.
• Content Management API (CMA): If your application requires programmatic content creation, updates, or deletions, you will need to use the Content Management API. This requires different access tokens with write permissions.
• GraphQL API: For applications that benefit from more efficient data fetching with specific data requirements, explore Contentful's GraphQL API. It allows clients to request exactly the data they need, avoiding over-fetching.

Troubleshooting the first call

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

• Incorrect Credentials: Double-check your Space ID and Content Delivery API access token. Ensure there are no typos and that you are using the correct token type (CDA for delivery, CMA for management).
• Unpublished Content: The Content Delivery API only returns published content. Verify that you have created and published at least one entry in your Contentful space. Draft content will not appear in CDA responses.
• Environment ID: By default, Contentful spaces use the master environment. If you've created custom environments, ensure your API request specifies the correct environment ID in the URL.
• Network Issues: Check your internet connection and ensure no firewall or proxy is blocking your request to cdn.contentful.com.
• API Endpoint: Confirm you are using the correct base URL for the Content Delivery API (https://cdn.contentful.com). The Content Management API uses a different base URL (https://api.contentful.com).
• Authorization Header Format: Ensure the Authorization header is correctly formatted as Bearer {YOUR_CDA_ACCESS_TOKEN}, with 'Bearer' followed by a space and then your token.
• Content Type ID Mismatch: If you are filtering by content type (e.g., ?content_type=blogPost), ensure the content_type parameter exactly matches the ID of a content type defined in your Contentful space.
• SDK Specific Errors: If using an SDK, consult the specific SDK's documentation for common errors and ensure all required parameters are provided. For example, the JavaScript SDK requires both space and accessToken in the client configuration.
• Contentful Status Page: Check the Contentful Status Page to see if there are any ongoing service disruptions or outages that might be affecting the API.