Skip to content

Introduction to the Management API

The Storyblok Management API follows REST principles. It has predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. The API uses built-in HTTP features, such as HTTP query parameters and HTTP verbs, which off-the-shelf HTTP clients understand. Further, it supports cross-origin resource sharing, allowing for secure interaction with the API from a client-side web application. All API responses, including errors, return JSON.

Use the Management API to create, edit, update, and delete content and configuration. To deliver content to end users, use the Content Delivery API instead, as it uses a global CDN for lower latencies.

Common use cases for the Management API:

  • Migrate content from a legacy CMS, for example with the Storyblok CLI
  • Integrate with third-party applications and services
  • Run programmatic content operations
  • Manage components, spaces, and configurations

The base URL for the Management API depends on the server location of the space. Below are the available endpoints for different regions:

https://mapi.storyblok.com/v1

Authenticate API requests with either a personal access token or an OAuth token.

The Management API uses standard HTTP response codes to indicate the success or failure of an API request.

To ensure fair usage and optimal performance, the Management API is subject to plan-based rate limits:

Plan Rate limit
Starter 3 requests per second
Growth, Growth Plus, Premium, Elite 6 requests per second

To ensure compliance with the rate limits, consider the following practices:

  • Throttle requests: if the API returns a 429 status code, slow down requests by introducing delays to allow graceful recovery.
  • Retry requests: implement a retry strategy with exponentially increasing delays for requests that fail due to rate limit errors.
  • Monitor usage: set up monitoring and alerting to track API usage and detect rate limit breaches early.

Most endpoints that return lists of resources support pagination, including stories, assets, datasources, datasource entries, tags, activities, and collaborators. Refer to the individual endpoint documentation for details.

Paginated endpoints accept two parameters:

  • page: The page number to retrieve. Increase this value to receive the next page of entries. Default is 1.
  • per_page: The number of entries per page. Default is 25. Maximum is 1000.

Paginated API requests include two properties in the response headers:

  • total: Indicates the total number of items available across all pages.
  • per_page: Specifies the number of items per page per request.

Use them to implement efficient pagination strategies.

Was this page helpful?

What went wrong?

This site uses reCAPTCHA and Google's Privacy Policy (opens in a new window).Terms of Service (opens in a new window) apply.