Workflow Tools

Tools for setting up and managing content approval workflows, workflow stages, and team collaboration processes in Storyblok.

Overview

Workflow tools help you implement structured content approval processes:

Workflows - Define approval processes for different content types
Workflow Stages - Create stages like "Draft", "In Review", "Approved"
Stage Changes - Move content through workflow stages
Approvals - Request and manage content approvals
Permissions - Control who can approve and publish

Total tools: 18 (Workflows: 6, Stages: 5, Stage Changes: 2, Approvals: 5)

Workflows (6 tools)

Workflows define approval processes that apply to specific content types.

Listing Workflows

retrieve_multiple_workflows

Purpose: Get all workflows in your space.

When to use:

See what approval processes exist
Find workflow IDs
Check which content types have workflows

Common conversation examples:

Show me all workflows in my space

What workflows are set up for blog posts?

Key parameters:

content_type - Filter by content type (optional)

Returns: Array of workflow objects.

retrieve_single_workflow

Purpose: Get details of a specific workflow.

When to use:

Inspect workflow configuration
Check stages and permissions
Understand workflow structure

Common conversation examples:

Show me details of workflow ID 123

What are the stages in the blog approval workflow?

Key parameters:

workflow_id - Workflow ID (required)

Returns: Single workflow object with complete configuration.

Creating Workflows

create_workflow

Purpose: Create a new workflow.

When to use:

Set up approval process for content type
Create editorial workflow
Define publishing gates

Common conversation examples:

Create a workflow called "Blog Approval" for blog_post content type

Set up a new workflow for product pages

Key parameters:

name - Workflow name (required)
content_types - Array of content types (required)

Returns: Newly created workflow object.

Tip: After creating a workflow, add stages with create_workflow_stage

Updating Workflows

update_workflow

Purpose: Update an existing workflow.

When to use:

Change workflow name
Add or remove content types
Modify workflow configuration

Common conversation examples:

Update workflow 456 to also apply to landing pages

Rename the workflow to "Editorial Review Process"

Key parameters:

workflow_id - Workflow to update (required)
name - New workflow name (required)
content_types - New content types array (required)

Returns: Updated workflow object.

duplicate_workflow

Purpose: Create a copy of an existing workflow.

When to use:

Use existing workflow as template
Create similar workflow for different content type
Test workflow changes

Common conversation examples:

Duplicate the blog workflow for news articles

Copy workflow 789 and name it "Product Review Process"

Key parameters:

workflow_id - Workflow to duplicate (required)
name - Name for new workflow (required)
content_types - Content types for new workflow (required)

Returns: Newly duplicated workflow object.

Deleting Workflows

delete_workflow

Purpose: Delete a workflow.

When to use:

Remove unused workflows
Clean up test workflows
Consolidate approval processes

Common conversation examples:

Delete workflow ID 321

Remove the old approval workflow

Key parameters:

workflow_id - Workflow to delete (required)

Returns: Deletion confirmation.

Warning: Cannot delete the default workflow. Stories using this workflow will revert to default.

Workflow Stages (5 tools)

Stages are the steps in a workflow (e.g., "Draft", "In Review", "Approved", "Published").

Listing Stages

retrieve_multiple_workflow_stages

Purpose: Get all workflow stages.

When to use:

See available stages
Find stage IDs
Check stage configuration

Common conversation examples:

Show me all workflow stages

List stages for workflow ID 123

Find the "Approved" stage

Key parameters:

in_workflow - Filter by workflow ID
search - Search by stage name
by_ids - Get specific stages by ID
exclude_id - Exclude specific stage

Returns: Array of workflow stage objects.

retrieve_single_workflow_stage

Purpose: Get details of a specific stage.

When to use:

Check stage permissions
See stage color and settings
Understand transition rules

Common conversation examples:

Show me details of stage ID 456

What permissions does the "In Review" stage have?

Key parameters:

workflow_stage_id - Stage ID (required)

Returns: Single workflow stage object.

Creating Stages

create_workflow_stage

Purpose: Create a new workflow stage.

When to use:

Add stages to workflow
Define review steps
Set up approval gates

Common conversation examples:

Create a stage called "Legal Review" with color red

Add an "SEO Check" stage to the blog workflow

Key parameters:

name - Stage name (required)
color - Stage color for UI (required)
workflow_id - Workflow this stage belongs to
is_default - Make this the default starting stage
allow_publish - Allow publishing from this stage
allow_all_stages - Allow transition to any stage
user_ids - Specific users allowed in stage
space_role_ids - Roles allowed in stage
workflow_stage_ids - Stages that can transition to this one
after_publish_id - Stage to move to after publish
position - Order position in workflow

Returns: Newly created workflow stage.

Permission options:

allow_all_users - Any user can access
allow_admin_change - Admins can move to stage
allow_editor_change - Editors can move to stage
allow_admin_publish - Admins can publish from stage

Updating Stages

update_workflow_stage

Purpose: Update an existing workflow stage.

When to use:

Change stage permissions
Update stage name or color
Modify transition rules
Reorder stages

Common conversation examples:

Update stage 789 to allow publishing

Change "Review" stage color to yellow

Add user 123 to the "Final Approval" stage

Key parameters:

workflow_id - Stage ID to update (required)
name - New stage name (required)
color - New stage color (required)
All other parameters same as create_workflow_stage

Returns: Updated workflow stage object.

Deleting Stages

delete_workflow_stage

Purpose: Delete a workflow stage.

When to use:

Remove unused stages
Simplify workflow
Clean up test stages

Common conversation examples:

Delete the "Optional Review" stage

Remove stage ID 999

Key parameters:

workflow_id - Stage ID to delete (required)

Returns: Deletion confirmation.

Warning: Cannot delete default stages. Move stories out of stage first!

Stage Changes (2 tools)

Move content through workflow stages.

retrieve_multiple_workflow_stage_changes

Purpose: Get history of stage changes.

When to use:

Track content movement
Audit approval history
See who moved content when

Common conversation examples:

Show me all stage changes for story 123

Get the workflow history

Key parameters:

space_id - Space ID (required)
with_story - Filter by story ID

Returns: Array of stage change records.

create_workflow_stage_change

Purpose: Move a story to a different workflow stage.

When to use:

Advance content through approval process
Send back for revisions
Mark content as approved

Common conversation examples:

Move story 456 to the "In Review" stage

Send this blog post to "Legal Review"

Mark story 789 as "Approved"

Key parameters:

story_id - Story to move (required)
workflow_stage_id - Destination stage ID (required)

Returns: Stage change record.

Important: User must have permission to move content to that stage!

Approvals (5 tools)

Request and manage content approvals from team members.

Listing Approvals

retrieve_multiple_approvals

Purpose: Get approval requests.

When to use:

See pending approvals
Check approval status
Find approvals for specific user

Common conversation examples:

Show me all approvals for user 123

What content is waiting for my approval?

Key parameters:

approver - User ID of approver (required)
page, per_page - Pagination

Returns: Array of approval objects.

retrieve_single_approval

Purpose: Get details of a specific approval.

When to use:

Check approval status
See who requested approval
Verify approval details

Common conversation examples:

Show me approval ID 456

What's the status of this approval request?

Key parameters:

approval_id - Approval ID (required)

Returns: Single approval object.

Creating Approvals

create_approval

Purpose: Request approval for a story.

When to use:

Submit content for review
Request publishing approval
Get stakeholder sign-off

Common conversation examples:

Request approval from user 789 for story 123

Submit this blog post to Sarah for approval

Key parameters:

story_id - Story needing approval (required)
approver_id - User who will approve (required)

Returns: Newly created approval request.

create_release_approval

Purpose: Request approval for a story in a specific release.

When to use:

Approve content as part of coordinated release
Get approval for scheduled publication
Manage release approvals

Common conversation examples:

Request approval for story 123 in release 456

Add this story to the Q1 launch release for approval

Key parameters:

story_id - Story needing approval (required)
approver_id - User who will approve (required)
release_id - Release ID (optional)

Returns: Newly created release approval.

Deleting Approvals

delete_approval

Purpose: Cancel an approval request.

When to use:

Withdraw approval request
Cancel outdated approvals
Remove completed approvals

Common conversation examples:

Cancel approval request 789

Delete the old approval and create a new one

Key parameters:

approval_id - Approval to delete (required)

Returns: Deletion confirmation.

When to Use What

Setting Up Workflows

Goal	Best Tool	Example
Create workflow	`create_workflow`	"Create blog approval workflow"
Add stages	`create_workflow_stage`	"Add 'Legal Review' stage"
Duplicate workflow	`duplicate_workflow`	"Copy blog workflow for news"
List workflows	`retrieve_multiple_workflows`	"Show all workflows"

Managing Stages

Goal	Best Tool	Example
Create stage	`create_workflow_stage`	"Add 'SEO Check' stage"
Update permissions	`update_workflow_stage`	"Allow editors to publish from this stage"
Reorder stages	`update_workflow_stage`	"Move stage to position 2"
Delete stage	`delete_workflow_stage`	"Remove unused stage"

Moving Content

Goal	Best Tool	Example
Move to stage	`create_workflow_stage_change`	"Move to 'In Review'"
Check history	`retrieve_multiple_workflow_stage_changes`	"Show stage history for story"

Approval Requests

Goal	Best Tool	Example
Request approval	`create_approval`	"Request approval from Sarah"
Check pending	`retrieve_multiple_approvals`	"Show my pending approvals"
Cancel request	`delete_approval`	"Cancel approval 123"
Release approval	`create_release_approval`	"Approve for Q1 release"

Common Patterns

Basic Editorial Workflow Setup

Create a three-stage editorial workflow:
1. Create workflow for "blog_post" content type
2. Create "Draft" stage (default, all users)
3. Create "In Review" stage (editors only)
4. Create "Approved" stage (allow publish, editors only)

Uses: create_workflow → create_workflow_stage (3 times)

Content Approval Process

Submit content for approval:
1. Move story to "In Review" stage
2. Request approval from editor
3. Editor reviews and approves
4. Move to "Approved" stage
5. Publish content

Uses: create_workflow_stage_change → create_approval → create_workflow_stage_change → publish_story

Multilevel Approval

Set up workflow with multiple approval gates:
1. Create stages: Draft → Content Review → Legal Review → Final Approval → Published
2. Set permissions: only specific users can move between stages
3. Require approval at each gate

Uses: create_workflow → create_workflow_stage (5 times with permissions)

Audit Workflow History

Track how content moved through workflow:
1. Get all stage changes for a story
2. See who moved it when
3. Verify approval compliance

Uses: retrieve_multiple_workflow_stage_changes → retrieve_multiple_approvals

Guides

Examples

Conversation Starters

Tips & Best Practices

Start simple - Begin with 3-4 stages, add more as needed
Clear stage names - Use names that describe purpose ("Awaiting Legal" vs "Stage 3")
Use colors wisely - Color-code by urgency (red=needs attention, green=approved)
Set default stage - Make "Draft" the default so new content starts there
Limit publish permissions - Only allow publish from final approval stages
Document process - Train team on workflow stages and transitions
Audit regularly - Check stage change history for bottlenecks
Use approvals - Formal approval requests create accountability
Test workflows - Create test content to verify workflow logic
Don't over-complicate - More stages = slower content velocity

Workflow Stage Permissions Explained

Who can access a stage:

allow_all_users: true - Anyone can move content to this stage
user_ids: [123, 456] - Only specific users
space_role_ids: [1, 2] - Only specific roles
allow_admin_change: true - Admins can move content here
allow_editor_change: true - Editors can move content here

Who can transition from a stage:

allow_all_stages: true - Can move to any stage from here
workflow_stage_ids: [789] - Can only move to specific stages

Publishing permissions:

allow_publish: true - Users can publish from this stage
allow_admin_publish: true - Admins can publish from this stage
after_publish_id: 456 - Auto-move to this stage after publish

Need help with workflows? Check out our workflow automation guide for detailed setup instructions!