The Most Helpful Storyblok Management API Endpoints for Provisioning a New Space
A practical guide to the key Management API endpoints for automating space setup, from preview URLs and folders to apps, assets, workflows, tags, and space-level configuration.
Storyblok spaces often start from the same set of decisions: the content model, folders, preview URLs, apps, workflow setup, assets, and a few space-level settings. These decisions are easy to apply manually once. They become harder when the same setup has to be repeated across customers, regions, environments, or spaces.
The Storyblok Management API is important because it turns these setup steps into repeatable operations. Instead of relying on a checklist in the UI, a team can create, configure, organize, and update a space programmatically.
The Management API covers many areas of Storyblok. You can manage spaces, stories, folders, components, assets, datasources, workflows, collaborators, releases, apps, and more. This article is not a complete endpoint reference. It is a practical guide to the endpoint groups that, in my opinion, are the most relevant when provisioning and setting up a new Storyblok space.
The Provisioning Problem
A new Storyblok space is rarely just an empty container. It usually needs a predictable structure before developers and editors can work efficiently.
Typical setup tasks include:
Creating a blank space or duplicating a template space.
Waiting until the duplicated space is ready.
Configuring preview URLs for frontend environments.
Removing demo mode from a production-like space.
Installing required apps.
Creating folders and moving content into the right structure.
Configuring Dimensions or translation-related metadata.
Uploading reusable assets.
Adding fields to existing components.
Assigning workflow stages and content tags.
Enabling space-level AI settings where needed.
Doing this manually is possible, but it is slow and difficult to audit. The main issue is not only speed. The real issue is consistency. A small difference in a preview URL, folder slug, app installation, or component field can create different behavior across spaces.
The Management API solves this by exposing space setup as data operations. This matters for automation and integrations because setup becomes part of a controlled process. A CI pipeline, an internal platform, an onboarding script, or a migration tool can apply the same operations with the same rules.
Why the Management API Matters for Automation
The Management API is useful when a process needs to change Storyblok, not only read content from it.
The Content Delivery API is optimized for consuming content. The Management API solves a different problem. It allows systems to create content, update configuration, organize folders, install apps, upload assets, and manage editorial workflows.
That makes it useful in several scenarios:
Creating demo spaces from a template.
Preparing customer sandboxes.
Setting up regional spaces with the same structure.
Running migration scripts.
Creating internal self-service tools.
Connecting Storyblok with CI/CD workflows.
Applying governance rules across multiple spaces.
The value is not only speed. The main value is consistency. When setup is managed through API calls, the process can be reviewed, tested, repeated, and improved over time.
A Practical Provisioning Flow
For provisioning, the most useful approach is not to call one endpoint in isolation. The better pattern is to combine a small set of endpoint groups into a repeatable workflow.
The workflow usually looks like this:
Create or duplicate the target space.
Read the space until background tasks are complete.
Update space-level settings.
Create or reuse folders.
Move content into the target structure.
Install apps and configure app-related settings.
Upload assets and create asset folders.
Update components.
Assign workflow stages and tags.
Each step maps to a different part of the Management API. Some steps are simple updates. Others require reading the current state first, resolving IDs, then applying only the missing changes.
That is why endpoint selection matters. Storyblok has many Management API endpoints, but provisioning usually depends on a smaller set of high-impact areas.
Spaces
The Spaces endpoints are the starting point for provisioning. They cover creating a new space, duplicating an existing space, reading the space, and updating space-level configuration.
Important operations:
POST /v1/spacesGET /v1/spaces/:space_idPUT /v1/spaces/:space_id
Creating a blank space is useful when the setup script will build most things from scratch. Duplicating a space is useful when you already have a template space with components, content examples, workflows, or app setup that should be reused.
Duplication is especially helpful for demos and customer-specific sandboxes. It gives you a known baseline, then the setup layer can adjust only what needs to change.
The update operation is also important because several setup settings live on the space object. Preview configuration, demo mode, AI flags, organization AI inheritance, and AI Translation disclaimer acceptance can all be treated as space-level updates.
The practical impact is simple: the space becomes reproducible. You can create a new environment from the same baseline and apply the same configuration every time.
Reference: Create a Space, Duplicate a Space, and the Storyblok Management API.
Preview URLs
Preview URLs are one of the first settings a team needs after creating a space. Without them, editors cannot open the right frontend preview from the Visual Editor or entry screen.
Important operations:
GET /v1/spaces/:space_idPUT /v1/spaces/:space_id
Preview configuration usually lives on the space object. A setup script can read the current space, compare the default preview URL and frontend environments, then update only the missing or changed values.
For example, the update payload may include preview settings for the space:
{
"space": {
"default_root": "https://demo.example.com/?token=SPACE_PREVIEW_TOKEN&path=",
"environments": [
{
"name": "Local Development",
"location": "https://localhost:3000/?token=SPACE_PREVIEW_TOKEN&path="
},
{
"name": "Staging",
"location": "https://staging.example.com/?token=SPACE_PREVIEW_TOKEN&path="
}
]
}
}
The preview token is space-specific, so it should not be hardcoded in reusable setup files. A provisioning layer can read it from the target space and inject it into the configured URL.
This is useful for demos, sandboxes, and multi-environment projects. Editors get working previews immediately, and developers avoid manually copying tokens into URLs for every new space.
Reference: Storyblok Management API, using the space read and update operations.
Stories and Folders
Storyblok folders are managed through the Stories endpoint. A folder is a story-like object with is_folder: true, a slug, a name, and a parent_id.
Important operations:
GET /v1/spaces/:space_id/storiesPOST /v1/spaces/:space_id/storiesPUT /v1/spaces/:space_id/stories/:story_id
This endpoint group is one of the most important for provisioning because content structure is part of the editor experience. A clean folder structure helps editors find content, separate countries or channels, and keep shared content away from page-specific content.
For example, a setup script can create folders with predictable slugs:
{
"story": {
"name": "Global",
"slug": "global",
"is_folder": true,
"parent_id": 0
}
}
For nested folders, the script usually resolves the parent folder first, then uses its ID:
{
"story": {
"name": "Archive",
"slug": "archive",
"is_folder": true,
"parent_id": 123456
}
}
The same endpoint group can move existing content by changing parent_id. This is useful after duplicating a template space, where some stories may initially live at the root. A provisioning script can move them into the correct folder without recreating them.
The important design detail is to reconcile by stable references, such as full slugs, instead of relying only on numeric IDs. Numeric IDs are created by Storyblok. Slugs are easier to keep in configuration and easier to review.
Reference: Create and Manage Folders.
Components
Components define the content model. The Components endpoints are useful when a setup process needs to adjust schemas, add fields, or install fields related to apps and plugins.
Important operations:
GET /v1/spaces/:space_id/componentsGET /v1/spaces/:space_id/components/:component_idPUT /v1/spaces/:space_id/components/:component_id
In a provisioning flow, component updates should be careful. The goal is not to overwrite the full content model every time. The safer approach is to add or update only the fields declared in the setup file and preserve unmanaged properties.
For example, a setup process can add a custom SEO field to an existing component:
{
"component": {
"name": "article-page",
"schema": {
"SEO": {
"type": "custom",
"field_type": "sb-ai-seo",
"display_name": "SEO"
}
}
}
}
This kind of operation is useful when a space needs a standard SEO field, integration field, or plugin field across multiple content types. Developers can keep the baseline component model in a template space, while setup scripts add the environment-specific fields needed for a scenario.
The impact is both technical and operational. Developers get a predictable schema. Editors get consistent fields in the same tabs across spaces.
Reference: Update a Component.
Apps and App Provisions
Many Storyblok setups depend on apps. Examples include Releases, Dimensions, AI SEO, import/export tools, backups, or AI Translations.
Important operations:
Retrieve available apps.
Retrieve installed app provisions.
Install an app provision for the space.
App provisioning matters because app setup is easy to miss in manual workflows. A duplicated space may not always contain the app state you expect, and a blank space usually needs apps installed before some features can be configured.
A setup script should keep app installation explicit. It can resolve an app by slug when possible, use the app ID when needed, then install it for the space.
{
"app_id": 29942
}
Using both slug and ID can be useful when a slug is not stable or not known for every app. In that case, the setup can resolve by slug when possible and use an ID fallback when needed.
The practical value is clear during repeatable demos and onboarding. Required apps become part of the space contract instead of a manual reminder.
Reference: Storyblok Management API, especially the app and app provision endpoint groups.
Assets and Asset Folders
Assets are often part of a reusable space setup. A demo space may need logos, sample images, icons, or brand assets. A customer starter space may need default folders for shared files.
Important operations:
GET /v1/spaces/:space_id/asset_foldersPOST /v1/spaces/:space_id/asset_foldersGET /v1/spaces/:space_id/assetsSigned upload response for assets.
Finish upload.
Asset provisioning is slightly different from content provisioning because upload usually has more than one step. The setup flow needs to create or reuse the target asset folder, request upload details, upload the file, and finish the upload.
For a provisioning script, the desired state can stay simple: create the target asset folder if it does not exist, then upload files that are not already present.
{
"asset_folder": {
"name": "Brand",
"parent_id": null
}
}
The important part is the reconciliation rule. A setup script should avoid replacing assets unless replacement is explicitly requested. For initial provisioning, skipping an asset with the same filename in the same folder is usually safer.
The impact is better repeatability. Demo assets and starter assets can travel with the setup configuration instead of being uploaded manually for each space.
Reference: Asset Folders and Assets.
Workflows and Workflow Stage Changes
Workflows are important when a space is used by real editors. A story without a workflow stage can be confusing in spaces where the editorial process matters. This is common after duplicating a space or importing content, because some stories may not be assigned to a stage yet.
Important operations:
Retrieve workflows.
Retrieve workflow stages.
Create workflow stage changes.
For setup, a common operation is assigning a default stage to stories that do not have one. The script can retrieve workflows, resolve the target stage, find stories without a stage, and create stage changes only for those stories.
{
"workflow_stage_change": {
"story_id": 123456789,
"workflow_stage_id": 987654321
}
}
When the target stage is not hardcoded, a setup tool can resolve the first stage of the default workflow. This keeps the process more portable when numeric workflow-stage IDs differ across spaces. If a specific workflow stage is required, the setup can use the explicit stage ID instead.
The important part is to apply the stage only where needed. A good setup process should not move every story to the same stage. It should detect stories without a workflow stage and create workflow stage changes only for those stories.
The impact is mainly editor experience. Content starts in a known workflow state, and the editorial process can begin without manual cleanup.
Reference: Workflows and Workflow Stage Changes.
Tags
Tags are useful for classifying stories after provisioning. They can mark configuration stories, landing pages, campaign content, migration batches, or content that belongs to a specific demo scenario.
Important operations:
Retrieve stories by slug or ID.
Update stories with merged tag lists.
Use tag endpoints when managing tag metadata directly.
For example, a setup process can read stories by slug, merge new tags with existing tags, and update each story:
{
"story": {
"tag_list": [
"Configuration",
"Landing"
]
}
}
For provisioning, tag assignment should normally merge with existing tags. Removing tags just because they are absent from the setup file can surprise editors and other automation.
The impact is traceability. Tags make it easier to understand why content exists and which setup process created or prepared it.
Reference: Tags and the story update operations in the Storyblok Management API.
Space-Level AI and Translation Settings
AI setup is a good example of why provisioning should treat apps and space settings separately.
Installing an AI-related app is one operation. Enabling Storyblok AI for the space is another. Accepting or configuring an AI Translation disclaimer is also separate.
This distinction is useful in implementation. App installation, AI activation, organization configuration inheritance, and AI Translation disclaimer acceptance should be handled as separate operations.
{
"space": {
"ai_text_generator_disabled": false,
"inherit_org_ai_configuration": false,
"disclaimer_id": 173657768407244
}
}
This maps back to space-level reads and updates. The setup process reads the current space, compares only the declared fields, and sends a partial update when something differs.
The impact is safer automation. A setup script can configure AI-related features without overwriting unrelated space settings.
Reference: Storyblok Management API, using the app provision and space update operations.
Why Reconciliation Matters
The most important part of provisioning is not only which endpoints are called. It is how they are called.
A good provisioning flow should be reconciliatory:
Read the current state first.
Create missing resources.
Update only declared settings.
Skip resources that already match.
Preserve unmanaged values.
Avoid deleting anything unless deletion is explicit.
This is different from a one-way import. A one-way import assumes the target should be replaced. A reconciliation flow assumes the target may already contain useful work and updates only the parts managed by the configuration.
That approach is important for Storyblok spaces because spaces are living environments. Editors may already be working. Developers may have added fields. Apps may have settings outside the scope of the setup script.
Business Value
Programmatic provisioning is not only a developer convenience. It improves the way teams operate Storyblok across projects.
For developers, it reduces manual setup and makes environments easier to reproduce. A new demo, sandbox, or regional space can be created from the same configuration.
For solution engineers, it makes demos more reliable. The same setup definition can prepare apps, folders, preview URLs, assets, and component fields before a customer session.
For content architects, it creates a shared contract. The setup is visible in code, reviewable in pull requests, and easier to compare across spaces.
For technical leaders, it reduces hidden operational work. Space setup becomes part of delivery automation instead of a manual checklist owned by one person.
Simplifying the Implementation
After identifying the most relevant Management API endpoints, the next step is deciding how much implementation you want to own.
You can call the Management API directly from your own scripts, internal tools, CI jobs, or migration processes. This gives you full control over the setup logic and how it fits into your architecture.
You can also use tools that wrap common provisioning scenarios into a higher-level configuration. For example, a tool like blokctl can describe a space setup in YAML and then call the Management API endpoints behind the scenes.
That kind of tool does not replace the Management API. It builds on top of it. The important part is understanding which Management API endpoints are relevant to your setup process, then deciding whether to call them directly or use a higher-level automation layer.
Conclusion
The most helpful Storyblok Management API endpoints for provisioning are the ones that define the shape and behavior of a space: Spaces, Stories and folders, Components, Apps, Assets, Workflows, Tags, and space-level feature settings.
Used together, these endpoints support a practical automation workflow. Your process can describe the desired state, and the Management API can apply that state in a repeatable way.
That is the key value of the Management API for setup work. It turns space provisioning from a manual sequence of UI actions into a controlled, reviewable, and repeatable process.