Contentstack Getting Started: Account, Keys, First Request (2026)

Getting started overview

To begin retrieving content from Contentstack, developers register for an account, establish a content stack, and obtain the necessary API credentials. These credentials typically include an API Key, a Delivery Token, and an Environment Name, which authenticate requests to the Content Delivery API (CDA). The CDA serves read-only content from Contentstack, optimized for performance and scalability in front-end applications. For content manipulation, the Content Management API (CMA) is used, requiring different authentication methods such as authtokens or personal access tokens (PATs), generally for back-end or administrative tasks.

Contentstack provides Software Development Kits (SDKs) for various programming languages and frameworks, including JavaScript, Python, Swift, and .NET, which abstract the complexities of direct HTTP requests. Alternatively, direct HTTP requests to the REST or GraphQL APIs can be made. This guide focuses on the initial steps to configure your environment and execute a basic content retrieval operation.

Create an account and get keys

1. Sign Up for a Contentstack Account: Navigate to the Contentstack website and register for a new account. A Free Plan is available for initial development and testing.

2. Create a Stack: After logging in, create a new 'Stack'. A stack is an isolated repository for all your content, assets, and settings. Give your stack a descriptive name and select a region if prompted.

3. Define a Content Type: Before retrieving content, you need content to retrieve. Go to 'Content Models' in your Contentstack dashboard and click '+ New Content Type'. Define fields relevant to your content (e.g., 'Title' and 'Body' for a blog post). Save and publish your content type.

4. Add Content Entries: Once a content type is defined, go to 'Content' and create a new entry based on your content type. Populate the fields and 'Publish' the entry to an environment (e.g., 'development', 'production'). Contentstack environments define specific publishing targets for content.

5. Retrieve API Credentials: To connect your application to Contentstack, you will need specific API credentials for your stack. Go to 'Settings' > 'Stacks' in your Contentstack dashboard. Click on your stack, and then navigate to the 'API Keys' section. Here you will find:

   • API Key: A unique identifier for your stack.
   • Delivery Token: An authentication token specific to an environment (e.g., 'development' or 'production'). This token grants read-only access to published content.
   • Environment Name: The name of the environment (e.g., 'development') for which the Delivery Token is valid.

   Keep these credentials secure, as they provide access to your content. For a detailed guide on obtaining these, consult the Contentstack API Keys documentation.

Your first request

Making your first request involves using the Content Delivery API (CDA) to fetch content. This example demonstrates fetching entries for a specific content type using a direct HTTP request (cURL) and a JavaScript (Node.js) SDK call.

Direct HTTP Request (cURL)

Replace YOUR_API_KEY, YOUR_DELIVERY_TOKEN, YOUR_ENVIRONMENT_NAME, and YOUR_CONTENT_TYPE_UID with your actual credentials and content type UID.

curl -X GET \
  'https://cdn.contentstack.io/v3/content_types/YOUR_CONTENT_TYPE_UID/entries?environment=YOUR_ENVIRONMENT_NAME' \
  -H 'api_key: YOUR_API_KEY' \
  -H 'access_token: YOUR_DELIVERY_TOKEN'

This cURL command fetches all entries of a specified content type from your Contentstack stack. The API Key identifies the stack, the Delivery Token authorizes access to the environment, and the environment parameter specifies which published content set to retrieve.

JavaScript SDK Example (Node.js)

First, install the Contentstack JavaScript SDK:

npm install contentstack --save

Then, create a JavaScript file (e.g., fetchContent.js) and add the following code:

const contentstack = require('contentstack');

// Replace with your actual credentials
const Stack = contentstack.Stack({
  api_key: 'YOUR_API_KEY',
  delivery_token: 'YOUR_DELIVERY_TOKEN',
  environment: 'YOUR_ENVIRONMENT_NAME'
});

Stack.ContentType('YOUR_CONTENT_TYPE_UID')
  .Query()
  .limit(10) // Fetch up to 10 entries
  .find()
  .then(function success(result) {
    // Result is an array of entries
    console.log(result.items);
  })
  .catch(function error(err) {
    console.error(err);
  });

Execute this script using Node.js: node fetchContent.js. This will output an array of content entries from your specified content type, demonstrating successful communication with the Content Delivery API. For more SDK examples, refer to the Contentstack JavaScript SDK documentation.

Common next steps

Once you are successfully retrieving content, you can expand your integration:

• Explore Content Types and Fields: Define more complex content models, including modular blocks, references, and assets, to structure diverse content for your application. The Contentstack documentation on content types provides guidance.
• Integrate with a Frontend Framework: Utilize Contentstack's SDKs to seamlessly integrate content into popular frameworks like React, Next.js, Gatsby, or Vue.js. This involves setting up data fetching within your component lifecycle.
• Utilize GraphQL API: For more efficient and flexible data fetching, consider using Contentstack's GraphQL API. This allows clients to request only the data they need, reducing over-fetching and improving performance. For general GraphQL concepts, consult the official GraphQL documentation.
• Implement Webhooks: Set up webhooks to automatically trigger actions in external systems when content changes occur (e.g., clearing a CDN cache, rebuilding a static site, or sending notifications).
• Manage Assets: Learn how to upload, manage, and retrieve digital assets (images, videos, documents) through the Content Delivery API for Assets.
• Advanced Querying: Explore advanced querying capabilities of the CDA, such as filtering, sorting, pagination, and locale-specific content retrieval, to fine-tune the content delivered to your applications.

Troubleshooting the first call

Common issues encountered during the initial setup and content retrieval include:

• Incorrect API Credentials: Double-check that the API Key, Delivery Token, and Environment Name are exactly as provided in the Contentstack dashboard. Mismatches, typos, or using the wrong token for an environment (e.g., a development token for a production environment request) will result in authentication errors. Ensure no leading or trailing spaces are present.
• Content Not Published: Content entries must be published to the specific environment you are querying. If content is in 'Draft' state or published to a different environment, it will not be returned by the Content Delivery API for the targeted environment. Verify publication status in the Contentstack UI.
• Incorrect Content Type UID: The YOUR_CONTENT_TYPE_UID in your request must precisely match the unique identifier of your content type. This UID is typically found in the URL or settings of your content type in the dashboard.
• Network Issues or Firewall Restrictions: Ensure your development environment has unrestricted access to cdn.contentstack.io. Corporate firewalls or proxy settings can sometimes block external API calls.
• SDK Configuration Errors: If using an SDK, ensure it's initialized correctly with all required parameters. Refer to the specific Contentstack SDK documentation for your chosen language.
• Rate Limiting: While less common for initial calls, be aware that Contentstack's APIs have rate limits. Repeated, rapid requests during testing might temporarily trigger these limits. Consult the API Rate Limits documentation for details.

When encountering errors, review the error messages returned by the API or SDK, as they often provide specific indications of the problem. Contentstack's developer console in the UI can also provide insights into API activity and potential issues.