Introduction

The Storyblok Management API is organized around REST. 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 are understood by off-the-shelf HTTP clients. 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.

The Management API is designed for creating, editing, updating, and deleting 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:

• Content migration from a legacy CMS
• Integration with third-party applications and services
• Programmatic content operations
• Managing components, spaces, and configuration

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

https://api-us.storyblok.com/v1

https://api-ca.storyblok.com/v1

https://api-ap.storyblok.com/v1

https://app.storyblokchina.cn/v1

API requests must be authenticated by providing either a personal access token or an OAuth token. Learn more in the access tokens concept.

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

The Storyblok Management API is subject to rate limits to ensure fair usage and optimal performance. The following rate limits apply:

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

• Throttling: If a 429 status code is received, slow down requests by introducing delays to allow graceful recovery.
• Retrying: Implement a retry strategy with exponential backoff for failed requests due to rate limit errors.
• Monitoring: 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, collaborators, activities, and tags. 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 100 (1000 for datasource entries).

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 as per the request.

These values can be used to implement efficient pagination strategies.