> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Import & Export Workflows

> Move Workflows between projects, back-up complex logic graphs, and share automations with your teammates.

Design a Workflow once, reuse it everywhere. Overcut lets you **export** any existing Workflow as a portable JSON artifact and **import** that artifact into another project or workspace.

<CardGroup cols={2}>
  <Card title="Export" icon="download">
    Save the current Workflow as a <code>.json</code> file on your computer.
  </Card>

  <Card title="Import" icon="upload">
    Bring a Workflow <code>.json</code> file into Overcut, map its agents, and start iterating.
  </Card>
</CardGroup>

<Note>
  The feature is available on all plans. You need the <code>workflow\.view</code> permission to export and <code>workflow\.create</code> to import.
</Note>

***

## Export a Workflow

<Steps>
  <Step title="Open the Workflow in the Builder">
    Navigate to <code>Workflows</code> and select a Workflow.
  </Step>

  <Step title="Click the Export Button">
    In the builder top-bar, click the <code>Export</code> icon. Overcut immediately downloads a file named <code>`{{workflow-name}}.json`</code>.
  </Step>
</Steps>

***

## Import a Workflow

<Steps>
  <Step title="Start the Import">
    In an empty or existing project, open any Workflow in the Builder (or create a new one). Click the <code>Import</code> icon in the top-bar and select the <code>.json</code> file you exported earlier.
  </Step>

  <Step title="Review Details & Rename (optional)">
    Overcut parses the file and opens the <strong>Import Workflow</strong> dialog. The <code>Workflow Name</code> field is pre-filled from the file; change it if you’d like.
  </Step>

  <Step title="Map Agents">
    Every agent referenced in the file must be mapped to an <em>existing agent</em> in the current project. Use the dropdown for each row to select the correct agent role.
  </Step>

  <Step title="Import & Open">
    Click <code>Import</code>. After the server validates the mapping, a success toast appears with <code>Open Workflow</code>. Click it to jump straight into your new Workflow.
  </Step>
</Steps>

<Note title="Limitations (v1)">
  • The artifact only contains the Workflow definition, not run history or execution metrics.<br />
  • All agents must exist in the target project before import.<br />
  • Other external text references (e.g., repositories, labels) may need to be manually updated after the import.
</Note>

***

## JSON File Structure

Here’s a shortened example of the exported file. You generally won’t edit this by hand, but it can be useful for version control or advanced CI flows.

```json title="my-workflow.json" theme={null}
{
  "_formatVersion": "1.0.0",
  "workflow": {
    "name": "Mention",
    "definition": {
      "flow": [
        {
          "to": "git-clone",
          "from": "",
          "condition": null
        },
        {
          "to": "agent-session",
          "from": "git-clone",
          "condition": null
        }
      ],
      "name": "Mention",
      "steps": [
        {
          "id": "git-clone",
          "name": "Clone Repo",
          "action": "git.clone",
          "params": {
            "branch": "main",
            "cloneOptions": {},
            "repoFullName": "{{trigger.repository.fullName}}"
          },
          "instruction": null
        },
        {
          "id": "agent-session",
          "name": "Multi-Agent Session",
          "action": "agent.session",
          "params": {
            "goal": "Help the user with their questions",
            "agentIds": ["my-agent-id-1", "my-agent-id-2"],
            "exitCriteria": {
              "timeLimit": {
                "maxDuration": "2h"
              },
              "userSignals": {
                "explicit": ["/done", "thanks"]
              },
              "maxExchanges": 10,
              "maxUserSilence": "4h"
            },
            "resurrection": {
              "enabled": true,
              "preserveDays": 7,
              "restartCommands": ["bot /restart", "/continue"]
            },
            "interruptible": true
          },
          "instruction": "You are helping the user with their issue. Be helpful and concise."
        }
      ],
      "trigger": {
        "event": "mention",
        "conditions": {
          "field": null,
          "rules": [
            {
              "field": "context.repository.fullName",
              "rules": null,
              "value": "my-org/my-repo",
              "operator": "equals",
              "combinator": null
            }
          ],
          "value": null,
          "operator": null,
          "combinator": "and"
        }
      },
      "version": "1.0.0",
      "priority": 5,
      "timeoutMs": null
    }
  },
  "refs": {
    "agents": [
      {
        "id": "my-agent-id-2",
        "name": "Senior Developer"
      },
      {
        "id": "my-agent-id-1",
        "name": "Product manager"
      }
    ]
  }
}


```

***

## Error Handling

If the file is invalid or an agent mapping is missing, Overcut shows a detailed error message. No changes are made until the import succeeds.

***

## Next Steps

* After you import a Workflow, it will be available in the <code>Workflows</code> page.
* You may want to look at the imported Workflow to add specific conditions or update references to repositories or labels.