Storyblok
Inspect component schemas and create, update, or publish stories in a configured Storyblok space
Connect Storyblok when a project needs to read or manage stories in one space. The connector keeps draft creation and publication separate, so an editing flow can review content before it becomes public.
Storyblok is a shared project connection. All published app users act through the same Storyblok personal access token and space.
Availability
A Swarmz administrator must show Storyblok under Platform config > Integrations. Storyblok does not require a Swarmz OAuth app. A workspace member supplies a Storyblok personal access token.
Before you connect
In Storyblok, open My account > Account settings > Personal access tokens. Create a token limited to the target space and the required Spaces, Components, and Stories scopes. Add an expiration when your operating policy requires one. Storyblok describes its personal access token scopes and rotation rules.
Record the numeric Space ID and its Region:
| Value | Storyblok region |
|---|---|
eu | European Union |
us | United States |
ca | Canada |
ap | Australia/Asia-Pacific |
cn | China |
Connect Storyblok
- In the Swarmz project, open Settings > Integrations and select Storyblok.
- Select Add connection.
- Enter the Space ID and Region.
- Paste the personal access token into API key and select Save connection.
Swarmz validates the exact space against the regional Storyblok Management API. The token is encrypted and never added to project source.
Available operations
| Operation | What it does | Limit per minute |
|---|---|---|
list_spaces | Lists spaces visible to the token | 30 |
list_components | Lists component schemas in the configured space | 30 |
list_stories | Lists story metadata without loading complete content | 30 |
get_story | Gets one story with its content | 30 |
create_story | Creates one draft story | 10 |
update_story | Replaces a story's complete draft name, slug, and content | 10 |
publish_story | Publishes the current draft | 10 |
create_story and update_story require a complete Storyblok content object. Publishing is a separate write and requires its own AI approval.
Ask the AI to use Storyblok
- “Read our Storyblok component schemas, then build a page that renders the existing
featureandctablocks.” - “Create a draft press-release story. Do not publish it.”
- “Build an editorial dashboard that lists stories and opens their draft content.”
- “Update this draft from the approved form values, then ask before publishing it.”
The generated app can list drafts for an internal editorial screen or render approved content through server routes. Do not use a Management API token directly in a public page.
Verify Storyblok
- List components and confirm one component name from the space.
- List stories and open a known draft.
- Create a disposable draft with a unique slug.
- Update its content and confirm the draft in Storyblok.
- Publish only in a test space, confirm the published state, then remove the test story in Storyblok.
Troubleshoot and recover
If setup reports Storyblok space configuration rejected, check the numeric space ID, region, token scope, and token expiry. A correct space ID sent to the wrong regional endpoint still fails.
If listing works but writes fail, add only the missing Stories permission or replace the token with a correctly scoped one. If an update removes fields, restore them from Storyblok history and send the complete content object on the next update.
To rotate the token, generate a replacement, edit the Swarmz connection, and verify list_stories before revoking the old token. Select Remove in Swarmz and revoke the token in Storyblok to disconnect fully.