Overview
Workflow portability lets you move configuration between projects without recreating it by hand. Import creates structured outputs, workflows, and backend-pipeline links from a versioned JSON document. Export creates a portable JSON document from an existing resource.
Imports are scoped to the project currently open in the Console. They are atomic: if any item fails validation or conflicts with the destination, ModelRiver creates nothing.
Permissions
- Organization owners and admins can preview and import configuration.
- Anyone with access to the project can export an individual workflow or structured output.
Export configuration
Exports are available from the Export action in an individual resource's row menu.
Export a workflow
- Open Workflows for the project.
- Open the row menu for the workflow you want to move.
- Select Export.
The download includes the selected workflow, its attached structured output, and every target workflow required by its backend-pipeline events. Target-workflow dependencies are included transitively, so the resulting file can be imported as one bundle.
Export a structured output
- Open Structured Outputs for the project.
- Open the row menu for the structured output.
- Select Export.
This download contains that structured output only. It does not include workflows that may use it.
Import configuration
You can start the same import flow from either Workflows or Structured Outputs.
- Open the destination project in the Console.
- Select Import.
- Choose a JSON file or paste JSON into the editor.
- Review the live preview, warnings, and field-level errors.
- Select Import, review the resource counts, and confirm.
The preview is authoritative: it checks the destination project, connected providers, model availability, quotas, duplicate names, schemas, and cross-resource references before you confirm. After a successful import, the affected lists refresh automatically.
Downloadable example
Download the complete version 1 example. It contains two test-mode workflows, two structured outputs, a fallback model, customer fields, and a three-step backend pipeline.
The example uses test_mode: true so it can be validated without provider credentials. Before using a workflow in production, disable test mode and select provider/model combinations that are available and connected in the destination project.
Version 1 format
Every file is a JSON object with exactly these top-level fields:
| Field | Required | Description |
|---|---|---|
version | Yes | Must be 1. |
structures | Yes | Array of structured-output definitions. |
workflows | Yes | Array of workflow definitions. |
Structured outputs
Each structure requires name, example, and schema; description is optional.
| Field | Description |
|---|---|
name | The name referenced by a workflow's structure field. |
description | Optional human-readable explanation. |
example | JSON sample data used by test mode and checked against the schema. |
schema | A supported JSON Schema object that accepts example. |
Workflows
Only name is always required. Omitted optional fields use their normal Console defaults.
| Field | Description |
|---|---|
name, description | Workflow identity and optional description. |
provider, model | Required when test_mode is false; the provider must be connected and the model available in the destination project. |
backups | Optional fallback array; each item contains provider and model. |
request_type | Request type, defaulting to chat. |
system_instructions | Optional workflow instructions. |
structure | Optional name of a structured output in the same import file. |
customer_fields | Optional business identifiers returned as customer data. |
test_mode | true skips provider/model availability checks because the workflow does not call a provider. |
delay_response, cache_window_seconds | Optional response-delay and cache settings. |
backend_pipeline | Object containing enabled and ordered events. |
Each event requires name and may have target_workflow. A target workflow is a linked AI step; it must be another workflow in the same file. Use unlinked backend events at the beginning and end of a pipeline, and linked target workflows only for intermediate events.
References, names, and splitting files
Names and references are normalized during import. Use clear, unique snake_case names and keep referenced names consistent throughout the file.
- A workflow's
structuremust be present in that same file. - An event's
target_workflowmust be present in that same file and cannot point back to itself. - A destination project never overwrites, merges, skips, renames, or reuses an existing workflow or structured-output name. A name conflict rolls back the whole import.
If a bundle is too large, split it only along independent dependency groups. Every imported workflow still needs its attached structure and any target workflows it references in its own file.
Validation and limits
The import accepts JSON format version 1 only. Unknown fields, invalid types, duplicate normalized names, unresolved references, unsupported models, and invalid schemas are rejected before records are created.
Current version 1 limits include:
| Limit | Maximum |
|---|---|
| Import file size | 8 MiB |
| Workflows per import | 100 |
| Structured outputs per import | 100 |
| Pipeline events per workflow | 6 |
| Fallbacks per workflow | 2 |
Structured-output examples must satisfy their JSON Schema. The safe schema profile supports local JSON Pointer references, but rejects external or recursive references and regular-expression keywords such as pattern and patternProperties.
An empty file ("structures": [] and "workflows": []) can be previewed but cannot be imported.
Troubleshooting
| Problem | What to do |
|---|---|
| A name is already reserved | Rename the item in the JSON or import into a project where that normalized name does not exist. |
| Provider is not connected or model is unavailable | Connect the provider in the destination project, choose an available model, or use test mode while preparing the workflow. |
| A structure or target workflow cannot be resolved | Include the referenced resource in the same file and check its normalized name. |
| Example does not match the schema | Correct the example or schema until the preview succeeds. |
| File exceeds a limit | Split only independent workflow groups, keeping all dependencies together. |
Security and sharing
Exports do not include provider credentials, API keys, budgets, logs, or runtime request data. They can still contain sensitive system instructions, schema examples, descriptions, and customer-field names.
Treat exported files as configuration that may be sensitive: store them in an approved location, review them before sharing, and do not commit them to a public repository.
Next steps
- Build a workflow: Create and configure workflows manually
- Structured outputs: Define response schemas and examples
- Multi-step pipelines: Configure backend and linked-workflow events