Menu

Mattering Automations Storyblok integration

Connect Storyblok to Mattering Automations: stories with publish and unpublish, components and their schemas, datasources, asset metadata, releases, tags, and workflow reads as workflow steps, authenticated with one personal access token and its region.

The Mattering Automations Storyblok integration adds the Storyblok Management API to your automation canvas: list and manage stories through their full lifecycle including publish and unpublish, create and curate components and their field schemas, manage datasources and their key and value entries, organize assets and their folders and edit asset metadata, batch story changes into releases and deploy them together, and read tags, workflows, workflow stages, tasks, presets, and space roles for the IDs and audits everything else needs.

The credential is a personal access token created in the Storyblok app, stored together with the region your spaces are hosted in, because Storyblok serves the Management API from a different host per region and a token only works against its own region's host. Setup takes a few minutes once the token exists, and this guide walks through each step, including the region detail that causes most first-connection failures, and ends with the full node reference.

The safety modeling is stated on the nodes rather than buried. Of the 45 nodes, 19 read and 26 act, and eight carry a destructive flag: Storyblok: Delete Story, Storyblok: Delete Component, Storyblok: Delete Component Folder, Storyblok: Delete Asset, Storyblok: Delete Asset Folder, Storyblok: Delete Datasource, Storyblok: Delete Datasource Entry, and Storyblok: Delete Release. Two update rules are written on the nodes themselves: a story's content object and a component's schema are replaced whole on update, so the loop is always read, edit, send the full object back. One seam is deliberate: the asset upload's middle step, posting file bytes to a signed S3 URL, runs outside the canvas.

Before you start

  • A Storyblok account with at least one space you own or administer. Personal access tokens are created per user and cover the spaces you own by default, restrictable to specific spaces with per-scope permissions.
  • Knowledge of where your spaces are hosted. Storyblok serves the Management API from regional hosts (EU is the default, with US, Canada, Asia-Pacific, and China regions), and the Mattering credential must carry the matching region.
  • A Mattering workspace with access to the Automations app.
  • Space IDs handy, or plan to fetch them with Storyblok: List Spaces as the first step: every other Storyblok node is space-scoped and needs one.

Create a Storyblok personal access token

Mattering authenticates to the Storyblok Management API with a personal access token. A token grants access to the spaces you own by default and can be restricted to specific spaces, with per-scope permissions covering stories, components, assets, datasources, and more. The credential stores two things: the token itself and the region your spaces are hosted in, because the Management API host depends on the space's region and a token only works against its own region's host.

Sign in to the Storyblok app, open My account, then Account settings, and select Personal access tokens.
Generate a new token. Restrict it to the specific spaces and scopes your workflows touch when you can; a narrower token is the safer habit for automation.
Copy the token and store it safely before you leave the page. Treat it like a password: it authenticates as you against every space it covers.
Confirm your spaces' hosting region. EU is the default and uses mapi.storyblok.com; US spaces use api-us.storyblok.com, Canada api-ca.storyblok.com, Asia-Pacific api-ap.storyblok.com, and China app.storyblokchina.cn.
A wrong region fails exactly like a wrong token: both return 401. If a token you just created is rejected, check the region before regenerating the token. An organization with spaces in more than one region needs one connection per region, because a token only sees spaces in its own region.

Connect Storyblok to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Storyblok from the list.
Click Create new credential, paste the personal access token, set the region if your spaces are not in the EU (blank means EU, the default), and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection. Mattering lists the spaces the token can see on its regional host: a success proves both the token and the region at once, and the result reports how many spaces the token can reach.
Click Connect. All 45 Storyblok nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a Storyblok section should list the query and action nodes. Drop Storyblok: List Spaces onto the canvas and run a test step. It is the integration's health probe: it needs no parameters, a success returns the spaces the token can access with the numeric space IDs every other node asks for, and a 401 means the token or the region is wrong. Remember it only shows spaces in the credential's region.

Next, copy a space ID and run Storyblok: List Stories against it, then Storyblok: List Components. Both are read-only, and together they hand you the ID currencies most workflows need: story IDs for the get, update, publish, and delete nodes, and component IDs with their full field schemas for the component nodes. Note that the story lister deliberately omits each story's content object; Storyblok: Get Story is the node that returns a story fully loaded. Everything in this verify path reads and nothing writes, so it is safe to re-run whenever you rotate the token.

Node reference

45 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 19

Storyblok: Get Asset

storyblok_get_asset

Fetch one asset: CDN filename URL, content type and size, metadata (alt, title, copyright), folder, and privacy flag.

Storyblok: Get Component

storyblok_get_component

Fetch one component with its full schema definition - the read to do before Update Component, since the schema is replaced whole.

Storyblok: Get Space

storyblok_get_space

Fetch one space with its full detail: domain, environments, plan, roles, and settings (more properties than the list endpoint returns).

Storyblok: Get Story

storyblok_get_story

Fetch one story fully loaded, INCLUDING its content object (the list endpoint omits content). The read to do before an update, since updates send the whole content object back.

Storyblok: List Asset Folders

storyblok_list_asset_folders

List the space's asset folders (nested via parent_id) with the numeric IDs the asset nodes use.

Storyblok: List Assets

storyblok_list_assets

List a space's assets with filters on filename, folder, alt text, title, copyright, and tags. Returns the numeric asset IDs used by the get, update, and delete nodes.

Storyblok: List Component Folders

storyblok_list_component_groups

List the space's component folders (component groups) with both identifiers each carries: the numeric id (path parameter for folder endpoints) and the uuid (what a component's component_group_uuid references).

Storyblok: List Components

storyblok_list_components

List a space's components (block definitions) with their numeric IDs and full field schemas, plus the space's component folders in the same response (data.component_groups).

Storyblok: List Datasource Entries

storyblok_list_datasource_entries

List a datasource's key/value entries. Select the datasource by numeric ID or slug (pagination is disabled when selecting by slug); pass a dimension ID to get each entry's dimension_value.

Storyblok: List Datasources

storyblok_list_datasources

List the space's datasources (named key/value collections) with their numeric IDs, slugs, and dimensions.

Storyblok: List Presets

storyblok_list_presets

List the space's component presets (pre-filled block values editors can insert), optionally filtered to one component.

Storyblok: List Releases

storyblok_list_releases

List the space's releases (scheduled content batches) with their numeric IDs, scheduled release_at time, and whether each has been released.

Storyblok: List Space Roles

storyblok_list_space_roles

List the space's custom roles with their permission sets and allowed content paths (useful for access audits).

Storyblok: List Spaces

storyblok_list_spaces

List the spaces the personal access token can access, with their numeric IDs, plan, and hosting region. Every other Storyblok node needs a space ID from here. Also the credential health check: a bad token returns 401. Note a token only sees spaces in the credential's region.

Storyblok: List Stories

storyblok_list_stories

List a space's stories (content entries) WITHOUT their content field, with filters on slug, tag, folder, publish state, release, and a content-wide text search. Returns the numeric story IDs used by the get, update, publish, and delete nodes.

Storyblok: List Tags

storyblok_list_tags

List the space's story tags with usage counts. Tag NAMES (not ids) are what stories carry in tag_list and what the with_tag filter takes.

Storyblok: List Tasks

storyblok_list_tasks

List the space's tasks - user-triggerable webhook calls (build triggers, syncs) defined in the space's settings.

Storyblok: List Workflow Stages

storyblok_list_workflow_stages

List the space's workflow stages (the steps stories move through) with their numeric IDs - the values the story lister's in_workflow_stages filter takes.

Storyblok: List Workflows

storyblok_list_workflows

List the space's content workflows with their numeric IDs and the content types each applies to.

Action nodes 26

Storyblok: Create Asset Folder

storyblok_create_asset_folder

Create an asset folder, optionally nested under a parent. Reversible with Storyblok: Delete Asset Folder.

Storyblok: Create Component

storyblok_create_component

Create a component (block definition). schema is a key-value object of field definitions, each with at least a type. Reversible with Storyblok: Delete Component.

Storyblok: Create Component Folder

storyblok_create_component_group

Create a component folder for organizing block definitions. Reversible with Storyblok: Delete Component Folder.

Storyblok: Create Datasource

storyblok_create_datasource

Create a datasource (a key/value collection usable in component options and via the Content Delivery API). Reversible with Storyblok: Delete Datasource.

Storyblok: Create Datasource Entry

storyblok_create_datasource_entry

Add a key/value entry to a datasource. Reversible with Storyblok: Delete Datasource Entry.

Storyblok: Create Release

storyblok_create_release

Create a release: a named batch that story changes can be saved into (via the story nodes' release_id) and deployed together, optionally scheduled. Reversible with Storyblok: Delete Release while undeployed.

Storyblok: Create Story

storyblok_create_story

Create a story (or folder) in a space. The content object must carry a component property naming its content type, and every nested component block needs a _uid. Created as a draft unless publish is set. Reversible with Storyblok: Delete Story.

Storyblok: Delete Asset

storyblok_delete_asset

DESTRUCTIVE: delete an asset. Stories referencing its CDN URL will show a broken file. Capture the asset object first with Storyblok: Get Asset if there is any doubt.

Storyblok: Delete Asset Folder

storyblok_delete_asset_folder

DESTRUCTIVE: delete an asset folder. The assets themselves are not deleted, but their folder organization is lost.

Storyblok: Delete Component

storyblok_delete_component

DESTRUCTIVE: delete a component definition permanently. Stories already using it keep their stored data but the block becomes undefined in the editor. Capture the schema first with Storyblok: Get Component.

Storyblok: Delete Component Folder

storyblok_delete_component_group

DESTRUCTIVE: delete a component folder (uses the NUMERIC folder id, not the uuid). Components in it are not deleted, only un-grouped.

Storyblok: Delete Datasource

storyblok_delete_datasource

DESTRUCTIVE: delete a datasource and EVERY entry in it, permanently. Export the entries first with Storyblok: List Datasource Entries if there is any doubt.

Storyblok: Delete Datasource Entry

storyblok_delete_datasource_entry

DESTRUCTIVE: delete one key/value entry from a datasource. Frontends reading the key get nothing back.

Storyblok: Delete Release

storyblok_delete_release

DESTRUCTIVE: delete a release. Story changes saved into it (and its schedule) are discarded rather than deployed.

Storyblok: Delete Story

storyblok_delete_story

DESTRUCTIVE: delete a story. It stops being delivered immediately and the docs make no promise an API delete is recoverable - capture it first with Storyblok: Get Story if there is any doubt. Deleting a folder affects its children.

Storyblok: Finish Asset Upload

storyblok_finish_asset_upload

Step 3 of the asset upload: finalize an upload after the file bytes were POSTed to the signed S3 post_url (externally - see Init Asset Upload). The asset becomes visible in the space afterwards.

Storyblok: Init Asset Upload (Signed Request)

storyblok_init_asset_upload

Step 1 of Storyblok's 3-step asset upload: request a signed S3 upload. Returns post_url and a fields object. Step 2 - POSTing the file bytes to post_url as multipart/form-data with every fields entry - must happen OUTSIDE the canvas (a worker or script); then run Storyblok: Finish Asset Upload with the returned id. Reversible with Storyblok: Delete Asset once finished.

Storyblok: Publish Story

storyblok_publish_story

Publish a story's current draft, making it live on the published version delivered to frontends. Storyblok models this as a GET with side effects. Reversible with Storyblok: Unpublish Story.

Storyblok: Unpublish Story

storyblok_unpublish_story

Unpublish a story: it disappears from the published version frontends deliver (the draft is kept). Storyblok models this as a GET with side effects. Reversible with Storyblok: Publish Story.

Storyblok: Update Asset

storyblok_update_asset

Update an asset's METADATA: alt text, title, copyright, source (via the meta_data object), move it to a folder, or toggle privacy/lock. To replace the file bytes use the upload flow, not this node. Only fields you fill are sent.

Storyblok: Update Asset Folder

storyblok_update_asset_folder

Rename an asset folder or move it under a different parent. Only fields you fill are sent.

Storyblok: Update Component

storyblok_update_component

Update a component definition. The schema object is REPLACED whole when sent - read it first with Storyblok: Get Component and send the full edited schema, or leave schema blank to keep it. A schema change affects every story using the component.

Storyblok: Update Datasource

storyblok_update_datasource

Rename a datasource or change its slug. Changing the slug breaks frontends fetching entries by the old slug.

Storyblok: Update Datasource Entry

storyblok_update_datasource_entry

Update an entry's key or value - the remote-config move: flip a value a frontend reads through the datasource. To set a per-dimension value, send dimension_value together with the dimension_id it belongs to. Only fields you fill are sent.

Storyblok: Update Story

storyblok_update_story

Update a story. IMPORTANT: content is REPLACED whole, not merged - read the story first with Storyblok: Get Story, modify its content object, and send it back. Only fields you fill are sent. publish=true publishes the result; false saves a draft without unpublishing.

Storyblok: Update or Deploy Release

storyblok_update_release

Update a release (rename, reschedule) or DEPLOY it now by setting do_release. Deploying publishes every story change in the release immediately and there is no single undo - reverting means unpublishing or re-editing each story. Test runs must leave do_release blank.

Using the integration

On the automation canvas

Storyblok nodes chain with every other node: a webhook from your editorial pipeline can run Storyblok: Create Story and then open an approval task in Mattering Productivity before anything publishes, a scheduled sweep can read Storyblok: List Components and write a schema inventory into a Mattering database, and Storyblok: List Assets can feed an alt-text cleanup that files its results as tasks. The space ID from Storyblok: List Spaces is the value every downstream node asks for first.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter can drive the same surface. An agent can survey a space with Storyblok: List Stories, fetch one fully loaded with Storyblok: Get Story, edit the content object, and save a draft with Storyblok: Update Story, leaving Storyblok: Publish Story behind a human approval. The read nodes are the safest surface to hand an agent; keep the eight destructive nodes behind conditions or approval steps.

Read first: content and schema are replaced whole

The two update rules that matter most are stated on the nodes. A story's content object is replaced whole on update, not merged, so the loop is Storyblok: Get Story, edit, then Storyblok: Update Story with the full content object; a partial object deletes the missing fields. A component's schema behaves the same way through Storyblok: Get Component and Storyblok: Update Component, with one mercy: leave schema blank on the update and the existing schema is kept. A schema change affects every story using the component, so audit before editing.

Releases and the deploy moment

Storyblok: Create Release makes a named batch, and story changes save into it through the story nodes' release_id field. The batch goes live together, either at its scheduled release_at time or when Storyblok: Update or Deploy Release runs with do_release set. Deploying publishes every story change in the release at once and there is no single undo: reverting means unpublishing or re-editing each story, which is why the node carries a loud warning and test runs must leave do_release blank. Storyblok: Delete Release discards an undeployed batch along with its schedule.

Datasource entries as remote configuration

A datasource is a named key and value collection, and Storyblok: Update Datasource Entry is the remote config move: flip a value a frontend reads through the datasource, no deploy needed. Per-dimension values ride along when you send dimension_value with its dimension_id. Export the current state first with Storyblok: List Datasource Entries, and be careful with Storyblok: Update Datasource: changing a datasource's slug breaks frontends fetching entries by the old slug.

Assets: metadata on the canvas, bytes outside it

Storyblok's asset upload is a three-step signed flow, and the integration is honest about which steps it owns. Storyblok: Init Asset Upload (Signed Request) requests the signed S3 upload and returns a post_url with a fields object; posting the raw file bytes to that post_url as multipart form data with every fields entry must happen outside the canvas, in a worker or script; then Storyblok: Finish Asset Upload finalizes it with the ID the init step returned, and the asset appears in the space. Everything after the bytes exist is canvas work: Storyblok: List Assets filters by filename, folder, alt text, title, copyright, and tags, and Storyblok: Update Asset edits metadata, moves folders, and toggles privacy, sending only the fields you fill.

The eight destructive nodes, gated

Storyblok: Delete Story stops a story being delivered immediately, and the docs make no promise an API delete is recoverable, so capture it first with Storyblok: Get Story; deleting a folder affects its children. Storyblok: Delete Datasource takes every entry in the collection with it, so export with Storyblok: List Datasource Entries first. Storyblok: Delete Component leaves stories' stored data intact but the block becomes undefined in the editor, so capture the schema with Storyblok: Get Component. The rest (Storyblok: Delete Component Folder, Storyblok: Delete Asset, Storyblok: Delete Asset Folder, Storyblok: Delete Datasource Entry, Storyblok: Delete Release) are smaller but equally final. The pattern for all eight is the same: read or export the thing first, and put the delete behind a condition, an approval task, or a manual run rather than a bare trigger.

Troubleshooting

Test Connection fails with a 401 error
Two credentials facts share this symptom, so check both. First the region: Storyblok serves the Management API from a different host per region, a token only works against its own region's host, and a wrong region returns the same 401 as a wrong token. The test message names the regional host it targeted; confirm it matches where your spaces are hosted. Then the token: check for leading or trailing whitespace from the copy, and confirm the token still exists under My account, Account settings, Personal access tokens in the Storyblok app.
List Spaces works but nodes against a specific space are refused
Personal access tokens can be restricted to specific spaces and carry per-scope permissions covering stories, components, assets, datasources, and more. A token restricted this way lists the spaces it can see and is then refused by node families or spaces outside its grants. Open the token in the Storyblok app and widen its space access or scopes, or create a broader token and update the credential. Also confirm you are using a space ID from the credential's own List Spaces output: a token never sees spaces in another region.
Update Story wiped fields out of the content
The content object is replaced whole on update, not merged: whatever you send becomes the story's entire content, and fields missing from the object are gone after the save. The safe loop is Storyblok: Get Story (the list node deliberately omits content), edit the returned content object, and send the whole thing back. Fields outside content, like name or tag_list, follow the gentler rule of only being sent when filled, so a tags-only update can safely leave content blank.
Update Component broke blocks in the editor
A component's schema is replaced whole when sent, exactly like story content: sending a partial schema deletes the missing field definitions, and every story using the component is affected. Read the definition first with Storyblok: Get Component, edit the full schema, and send it all back, or leave the schema field blank on the update to keep the existing schema untouched while renaming or regrouping the component.
Pagination looks broken: there is no total count in the output
Storyblok returns pagination totals in the total and per_page response headers, not the response body, so the node output does not carry them. Paginate by advancing the page parameter until a page comes back shorter than per_page. The default page size is 25 and the maximum is 100, so set per_page to 100 for sweeps. One more wrinkle on datasource entries: selecting the datasource by slug disables pagination on that lister, so select by numeric ID when you need to page.
Nodes start returning 429 during a large sweep
Storyblok's documented Management API rate limits are 3 requests per second on the Starter plan and 6 requests per second on Growth, Growth Plus, Premium, and Elite, and exceeding them returns HTTP 429. The nodes report the 429 on their output rather than silently retrying, so add wait steps between batches, spread scheduled sweeps apart, and prefer one filtered List call at per_page 100 over many Get calls.
A test run deployed a release
Storyblok: Update or Deploy Release does both jobs its name says: with do_release blank it renames or reschedules, and with do_release set it deploys, publishing every story change in the release immediately with no single undo. Test runs must leave do_release blank, and the deploy form of the node belongs behind an approval task or a manual run. If a deploy did fire, recovery is per story: unpublish or re-edit each affected story, using Storyblok: List Stories filtered by release to find them.
Finish Asset Upload fails or the asset never appears
The middle step of the three-step upload is the usual gap. Storyblok: Init Asset Upload (Signed Request) returns a post_url and a fields object, and the raw file bytes must be posted to that post_url as multipart form data carrying every entry of fields, which happens outside the canvas in a worker or script. Only after that POST succeeds can Storyblok: Finish Asset Upload finalize, using the ID from the init step's response in the same run. If finish fails, the bytes leg has not completed: check that the external POST included all the fields entries and the file, then run finish again.

Storyblok is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products