@mastra/core/dist/docs/references/reference-core-addStoredWorkflow.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Mastra.addStoredWorkflow()

> **Beta:** Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.

The `.addStoredWorkflow()` method validates a stored workflow definition and registers it as a live workflow on the instance, persisting it through the `workflowDefinitions` storage domain. Once registered, the workflow runs like any other workflow via [`getWorkflow()`](https://mastra.ai/reference/core/getWorkflow).

See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows) for a complete setup example and the [stored workflow definition reference](https://mastra.ai/reference/workflows/stored-workflow-definition) for the accepted fields and graph entries.

## Usage example

```typescript
await mastra.addStoredWorkflow({
  id: 'greeting-workflow',
  description: 'Returns a greeting for the supplied name',
  inputSchema: {
    type: 'object',
    properties: { name: { type: 'string' } },
    required: ['name'],
  },
  outputSchema: {
    type: 'object',
    properties: { message: { type: 'string' } },
    required: ['message'],
  },
  graph: [
    {
      type: 'mapping',
      id: 'create-greeting',
      mapConfig: JSON.stringify({
        message: { template: 'Hello, ${initData.name}!' },
      }),
    },
  ],
})

const run = await mastra.getWorkflow('greeting-workflow').createRun()
const result = await run.start({ inputData: { name: 'Ada' } })
```

## Parameters

**def** (`StoredWorkflowGraph`): The workflow definition: id, optional description and metadata, JSON Schema input/output schemas, optional state and request-context schemas, and the step graph.

## Returns

A promise that resolves once the definition is validated, registered, and persisted.

## Behavior

- The definition is fully validated (structure, references, schema flow) before anything is mutated. Agents, tools, and workflows referenced by the graph must already be registered on the instance.
- Adding a definition with an existing ID replaces both the stored definition and the live registration. In-flight runs keep the graph they started with.
- Without a storage adapter that supports the `workflowDefinitions` domain, the workflow is still validated and registered in memory, but the definition is lost on restart.
- To add a root workflow together with helper workflows it nests, use [`addStoredWorkflows()`](https://mastra.ai/reference/core/addStoredWorkflows).

## Related

- [Mastra.addStoredWorkflows()](https://mastra.ai/reference/core/addStoredWorkflows): Add a dependency-ordered bundle of definitions
- [Mastra.getWorkflow()](https://mastra.ai/reference/core/getWorkflow): Retrieve a registered workflow
- [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows): Set up and use stored workflows
- [Stored workflow definition](https://mastra.ai/reference/workflows/stored-workflow-definition): Definition fields and graph entries