Handling content using the management API
What is the Management API?
Our Management API allows deep integration with the CMS. It offers a programmatic approach to creating and updating your content.
The Storyblok Management API is based on REST. It allows you to create, edit, and update content using a common interface.
As part of the Management API's role, it offers export/import CSV, upload assets, and migrations. You will find all these examples in this documentation.
Basic URL
https://mapi.storyblok.com
You should not expose your secret API key in any public website’s client-side code.
Storyblok API libraries convert responses to appropriate language-specific objects.
Samples of the requests are on our Management API Reference page.
Use our sample requests with the API Authentication Token from your profile in the Storyblok application to test out the Management API. We explain more, including how to generate your own API Authentication Token, in the Authenticate with your OAuth token section.
See more details in our Management API documentation page.
Management API use cases
Migration from your current data storage / CMS
Integration with 3rd party applications
Import and Export automation
Automatic translation workflows
Component versioning
Whitelabel integrations
Storyblok’s Management API should be avoided if you intend to serve this content to your audience. This is because the Storyblok Management API doesn’t utilize our global CDN for your requests. In this case, use Content Delivery API.
Use cases | |
---|---|
Stories | Can be used to import, export, or modify content. |
Components | Can be nested in each other. Consists of fields types. |
Component Groups | Can be used to group components together. |
Assets | Each asset object references one of the uploaded images, videos, and documents. |
Asset Folders | Can be used to group assets together. |
Datasources | Can be used as a single or multiple choice for multi-language labels, categories, or anything similar to these. |
Datasource Entries | Each datasource entry is a set of an object which consists of a key and the value. |
Spaces | Can be used as a content repository to keep all relevant content in one place. |
Space Roles | Can be attached to collaborators to define their roles and permissions in dedicated spaces. |
Tasks | Can be used for triggering builds, product sync, and publishing tasks to send requests to one of the custom endpoints. |
Approvals | Can be used to send approval requests to another collaborator of the space. |
Activities | Can be created on an update, create and delete actions in Storyblok resources. (i.e. stories, components, spaces, datasources, etc) |
Presets | Can be used to define multiple default values for components. (i.e. multiple styles in one component) |
Field types | Can be used to extend the editor. (i.e. color picker, google map location selector, etc) |
Workflow Stage | Can be used to define workflow stages and rules to control what each user is allowed to do. |
Workflow Stage Changes | Can be the objects that are assigned to a dedicated content item. |
Releases | The response can be a release object. (i.e. id, name, release_at, branches_to_deploy) |
Branch deployments | The end point can be used to deploy branches. (/v1/spaces/:space_id/deployments) |
Authenticate with your OAuth token
Generate your API Authentication Token from your profile page. Go to the My Account, Account settings{1} and Personal access tokens{2}. Click Generate new Token{3} button.

My account screen to generate a new token
Export or Import a CSV into a folder
To export or import a CSV into a folder in Storyblok, we offer you a Node.js Script that allows you to do that.
The architecture of export/import
The Node.js script checks for column values. The values starting with http
will be detected. Node.js Scripts will download the original file into the ./images/
folder to upload those files to Storyblok.
Use case 1: Export data from Storyblok as CSV
Use case 2: Import data to Storyblok from CSV
Configuration options for the config.js file are below.
module.exports = {
storyblok: {
export: {
previewToken: 'YOUR_PREVIEW_TOKEN', // for export -> Delivery API
options: { // Content Delivery Parameters
// starts_with: '/your-folder-slug', // folder you want to export as CSV,
version: 'draft', // version of content that should be exported
per_page: 100, // 100 is max atm
page: 1 // can be upped as needed.
}
},
import: {
oauthToken: 'YOUR_OAUTH_MANAGEMENT_TOKEN', // for import -> Management API,
spaceId: 83418, // Space ID you want to import it
parentFolderId: 0, // Folder of the Parent ID
importFilePath: './import/import.csv', // File that should be imported
}
}
}
Export:
To export data from Storyblok as a CSV, configure the previewToken
with the preview token of the space. The export will be served at /export/<timestamp>.csv
.
As a final step, execute the command below.
npx run export
Import:
Import data to Storyblok from the CSV by obtaining the OAuth token as described in Authenticate with your OAuth token section. After filling out the suitable values in the config.js file, execute the command below.
npx run import
You can take a look at our GitHub repository about Storyblok import and export for more information.
curl "https://mapi.storyblok.com/v1/spaces/656/assets/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"filename\":\"your_file.jpg\",\"size\":\"400x500\"}"
Storyblok.post('spaces/656/assets/', {
"filename": "your_file.jpg",
"size": "400x500"
}).then(response => {
console.log(response)
}).catch(error => {
console.log(error)
})
Here are example requests utilizing an asset folder.
curl "https://mapi.storyblok.com/v1/spaces/606/assets/" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-d "{\"filename\":\"your_file.jpg\",\"size\":\"400x500\",\"asset_folder_id\":123}"
Storyblok.post('spaces/606/assets/', {
"filename": "your_file.jpg",
"size": "400x500",
"asset_folder_id": 123
}).then(response => {
console.log(response)
}).catch(error => {
console.log(error)
})
Post the image as form data to our Amazon S3 bucket.
Upload files, to complete the process, by using the received response. For example, you can use Node.js for that. With Node.js, you can use the Storyblok Management API to upload files by using a signed request. The example code is combined together with step 3 below.
Send another request to complete the process.
Storyblok retrieves the MIME type and the content length for assets.
const FormData = require('form-data')
const fs = require('fs')
const file = '/path_to/your_file.jpg'
const fileUpload = (signed_response_object, success, failed) => {
let form = new FormData()
// Step 2. apply all fields from the signed response object to the second request
for (let key in signed_response_object.fields) {
form.append(key, signed_response_object.fields[key])
}
// Step 2. also append the file read stream
form.append('file', fs.createReadStream(file))
// submit your form
form.submit(signed_response_object.post_url, (err, res) => {
if (err) throw err
// Step 3. complete the upload
Storyblok.get('spaces/606/assets/' + signed_response_object.id + '/finish_upload').then(response => {
console.log('https://a.storyblok.com/' + signed_response_object.fields.key + ' uploaded!')
}).catch(error => {
throw error
})
console.log('https://a.storyblok.com/' + signed_response_object.fields.key + ' uploaded!')
})
}
For more details, go to our Storyblok Management API documentation.
Use Promise Throttle (an NPM package) to limit promises run per unit time for rate-limited requests in a set amount of time.
Use async (an NPM package) together with Promise Throttle to provide functions for working with asynchronous JavaScript.
Migration use cases
Storyblok's Management API and automation can be used for migrations. Examples of migrations include:
Migration examples | |
---|---|
Change an image field | Make changes to the image field in the product component. |
Transform a Markdown field into a Richtext field | Transform a Markdown or HTML field into Richtext. |
Migrate spaces | Run and rollback migrations through Storyblok CLI. |
Import space schemas | Import components schema as JSON. |
Version spaces locally & Edit content in a local editor | Edit content in local text editor and push into Storyblok. |
Update a Story | Request to update a Story. |
Migrate content between languages | Define slugs for folders and stories in different languages. |
Migrate from WordPress to Storyblok | Migrate contents from monolithic to headless CMS, Storyblok |
Take a look at our Storyblok CLI for more details of these examples.
How to migrate spaces
Content migrations conveniently allow you to change fields of content. To migrate spaces, we recommend you use our new content migration feature from the Storyblok CLI.
There are 4 steps to migrate.
Creating a migration file
Execute the generate-migration
command to create a migration file. To migrate spaces, there is an option of space
for generate-migration
.
$ storyblok generate-migration --space <SPACE_ID> --component <COMPONENT_NAME> --field <FIELD>
A sample file will be created in the folder of migrations that looks like below.
module.exports = function (block) {
// change a string to boolean
// block.subtitle = !!(block.subtitle)
// transfer content from other field
// block.subtitle = block.other_field
}
You can manipulate the block variable to add or modify existing fields of the component in this migration function.
Running the migration file
Execute run-migration
command to run the migration file.
$ storyblok run-migration --space <SPACE_ID> --component <COMPONENT_NAME> --field <FIELD>
There is a —dryrun option to prevent executing updates and only show the changes in the command line.
$ storyblok run-migration --space <SPACE_ID> --component <COMPONENT_NAME> --field <FIELD> --dryrun
Publishing the content
To publish content, you can use —publish
and —publish-languages
options.
—publish
option: Specify one of the options.all
published
published-with-changes
—publish-languages=<LANGUAGE>
: Specify the language to update.—publish-languages=ALL_LANGUAGES
: Update all languages.
Rollback migrations
By running the run-migrations
command, a JSON file containing all the content before the change will be generated.
$ storyblok rollback-migration --space <SPACE_ID> --component <COMPONENT_NAME> --field <FIELD>
Rollback migrations don’t apply with —dryrun flag.
The saved content is always related to the last run-migration command.
How to export and import space schemas
Download your space's components schema as JSON. The pull-components command from Storyblok CLI will download 2 files to your local environment:
A file for components
A file for presets
$ storyblok pull-components --space <SPACE_ID>
To import, use the push-components command from Storyblok CLI. It allows you to push your components file to a space.
$ storyblok push-components <SOURCE> --space <SPACE_ID> --presets-source <PRESETS_SOURCE>
How to version space locally and edit component schemas
Download the schemas with Storyblok CLI's pull-components
to edit content in the local editor, and push it into Storyblok with Storyblok CLI's push-components
command as described in the How to import space schemas section. It allows you to download JSON files in order to edit them locally and push them to Storyblok.
How to Update a Story
If you change your component architecture or need to do a bulk action on all your content items, you can also build migrations by updating a Story. Example requests with curl and JavaScript are below. You can add the property "publish": 1
to the object to publish Stories immediately.
curl "https://mapi.storyblok.com/v1/spaces/606/stories/2141" \
-X PUT \
-H "Authorization: YOUR_OAUTH_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"story\":{\"name\":\"Story Name\",\"slug\":\"story-name\",\"id\":2141,\"content\":{\"component\":\"page\",\"body\":[]}},\"force_update\":1,\"publish\":1}"
// use the universal js client to perform the request
Storyblok.put('spaces/606/stories/2141', {
"story": {
"name": "Story Name",
"slug": "story-name",
"id": 2141,
"content": {
"component": "page",
"body": []
}
},
"force_update": 1,
"publish": 1
}).then(response => {
console.log(response)
}).catch(error => {
console.log(error)
})
The property force_update
will overwrite a locked story.
Here is the list of all the properties and descriptions.
Stories - Update a Story | |
---|---|
story | Full story object. |
story[name] | Name of the story is required. |
story[slug] | Slug is required. Can be used to identify the Story. |
story[content] | Object structure for content. |
story[default_root] | Default content type/root component. If is_folder is true, this is required. |
story[is_folder] | A folder will be created if the value is true. |
story[parent_id] | The id of the parent. |
story[disable_fe_editor] | Side by side editor will be disabled for all entries in a folder. |
story[path] | Can be used in the preview editor. |
story[is_startpage] | Startpage of the current folder. |
story[position] | Integer value of the position. |
story[first_published_at] | First publishing date. (YYYY-mm-dd HH:MM) |
story[translated_slug_attributes] | Can be used to add/modify/delete translated slugs/names if Translatable slugs app is installed. |
force_update | Can be used to overwrite a locked Story if the value is 1. |
release_id | Numeric ID of release. (optional) |
publish | Can be used to publish a Story if the value is 1. |
lang | Language code to publish the story individually. Enable it in the space settings. |
The example of story[translated_slugs_attributes]
can be[{lang: "de", slug: "startseite", name: "Startseite"}]
.
For more details, you can read Storyblok Management API documentation.
Migrate content between languages
With Translatable Slugs app in the Storyblok App Store, you can define slugs for folders and stories in different languages. Take a look at our Internationalization documentation page for more information.
Translatable slug for entry is for field-level translation. For more information, take a look at our Translatable slugs section.
Meta information is not translatable.
There’s Storyblok awesome repo to see useful migration packages.
Migrate content from WordPress to Storyblok
With the WordPress Importer for Storyblok plugin, you can migrate content from WordPress to Storyblok.
In order to use the script from WordPress Importer for Storyblok, import the script and initialize a new instance of the WP2Storyblok
class. You can then run the WP2Storyblok.migrate()
method. See the example below.
import {Wp2Storyblok} from './index.js'
const wp2storyblok = new Wp2Storyblok('http://yoursite.com/wp-json', {
token: 'storyblok-oauth-token',
space_id: 110836,
content_types: [
{
name: 'pages',
new_content_type: 'page',
folder: 'your-custom-folder',
schema_mapping: {
title: 'name',
'_links.wp:featuredmedia.0': 'content.preview_image',
content: {
field: 'content.body_items',
component: 'rich-text',
component_field: 'content'
}
}
}
]
})
wp2storyblok.migrate()
WordPress REST API must be publicly available during the migration process as the script from WordPress Importer for Storyblok won’t handle authentication.
Find more information about our WordPress Importer for Storyblok GitHub repository.
There is a hands-on tutorial blog post to migrate content from WordPress to Storyblok written by our ambassador, Alba Silvente.