Storyblok Getting Started Guide: Account, Keys, First Request (2026)

Getting started overview

Getting started with Storyblok involves a sequence of steps designed to enable developers to retrieve content from their Storyblok space quickly. The process begins with account creation and the setup of a new 'Space,' which acts as a container for content. Upon space creation, Storyblok automatically generates API tokens, specifically a Content Delivery API token, which is necessary for authenticating read-only requests for published content. Developers then use this token to make their first API call, commonly retrieving content entries via a RESTful endpoint. This initial interaction validates the setup and confirms access to the content stored within Storyblok.

Storyblok's architecture is built around a headless CMS model, which separates content management from content presentation. This approach allows content to be delivered via an API to any frontend application or device. For developers, this means flexibility in choosing their preferred technology stack, as Storyblok provides SDKs for various popular programming languages and frameworks, including JavaScript, React, Vue, and PHP. The Content Delivery API (CDA) is the primary interface for retrieving content, offering endpoints for fetching stories, assets, and other content types. Understanding the structure of the CDA is fundamental to integrating Storyblok content into applications effectively.

The following table provides a quick reference for the essential steps to get started:

Create an account and get keys

To begin using Storyblok, the initial step is to create an account. Storyblok offers a Community Free tier that includes access for one user, one space, 25,000 requests per month, and 500 assets, which is suitable for getting started and small projects. Registration can typically be completed using an email address or through single sign-on options.

Once registered and logged in, you will be prompted to create your first 'Space'. A Space in Storyblok is an isolated environment for managing content, similar to a project or a tenant. When creating a new Space, you will define its name and select a region for data storage. Upon successful creation, the Storyblok dashboard for that Space will load.

Within your newly created Space, navigate to the 'Settings' section, usually accessible via the left-hand sidebar. Under 'Settings', locate 'Access Tokens'. Here, you will find various API tokens. The most critical for initial content retrieval is the Content Delivery API (CDA) Token. This token is public and read-only, designed for fetching published content. It is typically a long alphanumeric string. Copy this token, as it will be required for all your content delivery API calls.

Storyblok also provides a Content Management API (CMA) Token for programmatic content creation, updating, and deletion, and a Preview Token for fetching unpublished content. For the purpose of getting started and making your first read request, the CDA Token is sufficient. It is important to handle API tokens securely, even public ones, to prevent unauthorized access to your content. While the CDA token is read-only for published content, protecting it is still a best practice for maintaining content integrity and monitoring API usage.

Your first request

After obtaining your Content Delivery API token, you are ready to make your first request to retrieve content from your Storyblok space. The Content Delivery API is a RESTful API, meaning it uses standard HTTP methods (primarily GET for delivery) and returns data in JSON format. The base URL for the Content Delivery API is generally api.storyblok.com/v2/cdn/.

A common first request is to fetch a list of 'stories' (content entries) from your space. Each Storyblok content entry is referred to as a 'story'. To do this, you will append the stories endpoint to the base URL and include your Content Delivery API token as a query parameter. You will also need to specify the version parameter, typically set to published for live content.

Example using cURL:

curl "https://api.storyblok.com/v2/cdn/stories?version=published&token=YOUR_CDA_TOKEN"

Replace YOUR_CDA_TOKEN with the actual Content Delivery API token you copied from your Storyblok space settings. Executing this cURL command in your terminal will send an HTTP GET request to the Storyblok API. If successful, the API will return a JSON object containing an array of stories from your space. The response will include metadata and the actual content fields defined in your Storyblok content types.

Example using JavaScript (Node.js with node-fetch):

const fetch = require('node-fetch');

const YOUR_CDA_TOKEN = 'YOUR_CDA_TOKEN';

async function getStories() {
  try {
    const response = await fetch(
      `https://api.storyblok.com/v2/cdn/stories?version=published&token=${YOUR_CDA_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("Failed to fetch stories:", error);
  }
}

getStories();

This JavaScript example demonstrates how to make the same request programmatically. Ensure you have node-fetch installed (npm install node-fetch) if running in Node.js. In a browser environment, the native fetch API can be used directly.

The JSON response will typically look like this (simplified):

{
  "stories": [
    {
      "id": 123456,
      "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "name": "My Home Page",
      "slug": "home",
      "full_slug": "home",
      "content": {
        "_uid": "98765432-10ab-cdef-1234-567890abcdef",
        "component": "page",
        "headline": "Welcome to our site!",
        "body": [
          // ... array of content blocks
        ]
      },
      "created_at": "2023-01-01T10:00:00.000Z",
      "published_at": "2023-01-01T10:05:00.000Z",
      // ... other story properties
    }
  ],
  "cv": 1672579500
}

The stories array contains objects, each representing a content entry. The content field within each story object holds the actual structured data you define in the Storyblok visual editor. Successful retrieval of this JSON data confirms that your API token is valid and your application can communicate with Storyblok's content delivery network.

Common next steps

After successfully making your first request, several common next steps can help you further integrate Storyblok into your development workflow:

1. Explore Content Types: Familiarize yourself with how to define and manage content types (often called 'blok' components) in the Storyblok visual editor. This is where you structure the data for your content. The Storyblok components guide provides detailed information on this topic.
2. Integrate with a Frontend Framework: Storyblok provides official SDKs and starter guides for popular frontend frameworks like React, Vue, Next.js, and Nuxt.js. Using an SDK simplifies content fetching and integration, often including features like the Visual Editor bridge for real-time content previews.
3. Set up Webhooks: To enable real-time updates in your application when content changes in Storyblok, configure webhooks. Webhooks allow Storyblok to notify your application (e.g., a build server or cache invalidation service) about content updates, ensuring your frontend always displays the latest published content. Twilio's webhook security guide offers general best practices for securing webhook endpoints, which are applicable to Storyblok integrations.
4. Implement Image Optimization: Storyblok includes an Image Service that allows for on-the-fly image manipulation and optimization. Learn how to use parameters in image URLs to resize, crop, and format images directly from the API, reducing frontend development effort and improving performance.
5. Internationalization (i18n): If your project requires multi-language support, explore Storyblok's internationalization features. You can configure different language versions for your content directly within the Storyblok space and retrieve specific language versions via the Content Delivery API.
6. Content Management API (CMA): For advanced use cases, such as migrating content or building custom content import/export tools, investigate the Storyblok Content Management API. This API allows programmatic creation, updating, and deletion of content, requiring a more permissive API token.

Troubleshooting the first call

When making your first API call to Storyblok, you might encounter issues. Here are common problems and their solutions:

• 401 Unauthorized Error:
  • Issue: This typically means your API token is incorrect or missing.
  • Solution: Double-check that you have copied the correct Content Delivery API (CDA) token from your Storyblok Space Settings > Access Tokens. Ensure there are no leading or trailing spaces in the token. Verify that the token is correctly included as a query parameter (?token=YOUR_CDA_TOKEN) in your request URL.
• 404 Not Found Error:
  • Issue: The requested resource (e.g., a story or asset) does not exist, or the URL path is incorrect.
  • Solution: Verify the base URL for the Content Delivery API is https://api.storyblok.com/v2/cdn/. Check the endpoint you are trying to access (e.g., /stories, /stories/SLUG, /assets). Ensure that the content you are trying to fetch actually exists and is published in your Storyblok space.
• No Content in Response (Empty Array):
  • Issue: The API call is successful, but the stories array in the JSON response is empty.
  • Solution: This usually means there is no published content in your Storyblok space, or your query parameters are too restrictive. Ensure you have created and published at least one story in your space. Check if you are using specific filters or language parameters that might be excluding all content. Make sure the version=published parameter is correctly set to retrieve live content.
• CORS Errors (in browser environments):
  • Issue: Requests from a browser-based application fail due to Cross-Origin Resource Sharing (CORS) policies.
  • Solution: Storyblok's Content Delivery API generally supports CORS for common origins. If you encounter CORS issues, ensure your browser-based application's domain is correctly configured in your Storyblok space settings under 'CORS origins' if necessary. For local development, some development servers or browser extensions might interfere with CORS, but Storyblok's API is designed to be accessible from web frontends.
• Incorrect API Version:
  • Issue: Using an outdated or incorrect API version in the URL.
  • Solution: Always use /v2/cdn/ for the latest Content Delivery API. Refer to the Storyblok Content Delivery API reference for the most up-to-date endpoints and parameters.