Skip to main content
Version: 2026.1

Studio Integration

Studio API Endpoints​

The Workflow Designer Bundle provides a RESTful API for the Pimcore Studio interface, enabling management of workflow configurations, import/export, and user/role lookups. All endpoints are prefixed with /pimcore-studio/api/bundle/workflow-designer and require appropriate permissions.

Workflow Management​

List Workflows​

Endpoint: GET /workflows Operation ID: bundle_workflow_designer_list Permission: WORKFLOW_DESIGNER

Lists all available workflow configurations as a tree structure with folders.

Response: Collection of WorkflowListItem objects

Get Workflow​

Endpoint: GET /workflows/{name} Operation ID: bundle_workflow_designer_get Permission: WORKFLOW_DESIGNER

Retrieves a single workflow configuration by name including places, transitions, global actions and BPMN diagram.

Path Parameter:

  • name (string): The name of the workflow

Response: WorkflowDetail object

Example:

GET /workflows/simple_asset_workflow

Create Workflow​

Endpoint: POST /workflows Operation ID: bundle_workflow_designer_create Permission: WORKFLOW_DESIGNER

Creates a new workflow configuration with the given display label. The workflow name is automatically generated from the label.

Request Body: JSON object with:

  • name (string, required): Display label for the workflow (e.g., "My Workflow")

Response: WorkflowDetail object (HTTP 200)

Example:

POST /workflows
Content-Type: application/json

{"name": "My Workflow"}

Save Workflow​

Endpoint: PUT /workflows/{name} Operation ID: bundle_workflow_designer_save Permission: WORKFLOW_DESIGNER

Saves/updates a workflow configuration including places, transitions, global actions and diagram.

Path Parameter:

  • name (string): The name of the workflow

Request Body: JSON object with:

  • general (object, required): General workflow settings (label, type, support_strategy, marking_store, etc.)
  • places (object, required): Places configuration keyed by place name
  • transitions (object, required): Transitions configuration keyed by transition name
  • globalActions (object, optional): Global actions configuration (default: {})
  • diagram (string, optional): BPMN diagram XML string (default: "")
  • mode (string, optional): Save mode - regular (default) or reset (clears cache)

Response: JSON {"success": true} (HTTP 200)

Example:

PUT /workflows/wfdesigner_my_workflow
Content-Type: application/json

{
  "general": {
    "label": "My Workflow",
    "enabled": true,
    "type": "workflow",
    "support_strategy": {
      "type": "expression",
      "arguments": [
        "\\Pimcore\\Model\\Asset",
        "is_fully_authenticated()"
      ]
    },
    "marking_store": {"type": "state_table"}
  },
  "places": {
    "open": {"label": "Open", "color": "#3572b0"},
    "closed": {"label": "Closed", "color": "#008000"}
  },
  "transitions": {
    "close_it": {
      "from": ["open"],
      "to": ["closed"],
      "options": {"label": "Close It"},
      "name": "close_it"
    }
  },
  "mode": "regular"
}

Delete Workflow​

Endpoint: DELETE /workflows/{name} Operation ID: bundle_workflow_designer_delete Permission: WORKFLOW_DESIGNER

Deletes a workflow configuration by name.

Path Parameter:

  • name (string): The name of the workflow to delete

Response: HTTP 200 OK (empty response)

Example:

DELETE /workflows/wfdesigner_my_workflow

Import / Export​

Export Workflow​

Endpoint: GET /workflows/{name}/export Operation ID: bundle_workflow_designer_export Permission: WORKFLOW_DESIGNER

Exports a workflow configuration as a downloadable JSON file.

Path Parameter:

  • name (string): The name of the workflow to export

Response: JSON file download with Content-Disposition header

Example:

GET /workflows/simple_asset_workflow/export

Import Workflow​

Endpoint: POST /workflows/import Operation ID: bundle_workflow_designer_import Permission: WORKFLOW_DESIGNER

Imports a workflow configuration from an uploaded JSON file.

Request Body: Multipart form data with file field containing the JSON workflow configuration file

Response: JSON object with name of the imported workflow (HTTP 201 Created)

Possible Errors:

  • 400 Bad Request: No file uploaded or failed to read file contents
  • 409 Conflict: A workflow with the same name already exists

Example:

POST /workflows/import
Content-Type: multipart/form-data

Support Elements​

List Support Elements​

Endpoint: GET /support-elements Operation ID: bundle_workflow_designer_support_elements Permission: WORKFLOW_DESIGNER

Returns all supported element types including Document, Asset, DataObject types and class definitions. These are used when configuring which element types a workflow applies to.

Response: Collection of SupportElement objects

Example:

GET /support-elements

Users and Roles​

Search Users​

Endpoint: GET /users Operation ID: bundle_workflow_designer_user_search Permission: WORKFLOW_DESIGNER

Searches for users by name, firstname, lastname, email or ID.

Query Parameters:

  • query (string): Search query (e.g., "admin")

Response: Collection of UserSearchResult objects

Example:

GET /users?query=admin

Search Roles​

Endpoint: GET /roles Operation ID: bundle_workflow_designer_role_search Permission: WORKFLOW_DESIGNER

Searches for roles by name.

Query Parameters:

  • query (string): Search query (e.g., "editor")

Response: Collection of RoleSearchResult objects

Example:

GET /roles?query=editor

Permissions​

The Studio API uses the following permission constant:

  • WORKFLOW_DESIGNER: Required for all workflow management operations (permission_workflow_designer)

Common Response Codes​

  • 200 OK: Successful request
  • 201 Created: Resource created successfully (import)
  • 400 Bad Request: Invalid request data (import failures)
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: User lacks required permissions
  • 404 Not Found: Workflow not found
  • 409 Conflict: Duplicate workflow name (import)

API Tags​

All endpoints are tagged with Workflow Designer for OpenAPI documentation grouping.

Usage Examples​

Creating and Managing Workflows​

  1. Create a new workflow:

    POST /workflows
    {"name": "Product Approval"}

  2. Get workflow details:

    GET /workflows/wfdesigner_product_approval

  3. Save workflow configuration:

    PUT /workflows/wfdesigner_product_approval
    {
      "general": {"label": "Product Approval", ...},
      "places": {"draft": {"label": "Draft"}, ...},
      "transitions": {"submit": {...}, ...},
      "mode": "regular"
    }

  4. Export for backup:

    GET /workflows/wfdesigner_product_approval/export

  5. Delete workflow:

    DELETE /workflows/wfdesigner_product_approval

Import / Export​

  1. Export a workflow:

    GET /workflows/simple_asset_workflow/export

  2. Import a workflow:

    POST /workflows/import
    Content-Type: multipart/form-data

Looking Up Users and Roles​

  1. Search for users:

    GET /users?query=admin

  2. Search for roles:

    GET /roles?query=editor