---
title: "Reference: workflowRoute() | AI SDK"
description: API reference for workflowRoute(), a function to create workflow route handlers for streaming workflow execution in AI SDK-compatible format.
packages:
  - "@mastra/ai-sdk"
  - "@mastra/core"
---

import PropertiesTable from "@site/src/components/PropertiesTable";

# workflowRoute()

Creates a workflow route handler for streaming workflow execution using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts input data, executes a workflow, and streams the response back to the client in AI SDK-compatible format. You have to use it inside a [custom API route](/docs/v1/server/custom-api-routes).

Use [`handleWorkflowStream()`](/reference/v1/ai-sdk/handle-workflow-stream) if you need a framework-agnostic handler.

:::tip Agent streaming in workflows

When a workflow step pipes an agent's stream to the workflow writer (e.g., `await response.fullStream.pipeTo(writer)`), the agent's text chunks and tool calls are forwarded to the UI stream in real time, even when the agent runs inside workflow steps.

See [Workflow Streaming](/docs/v1/streaming/workflow-streaming#streaming-agent-text-chunks-to-ui) for more details.

:::

## Usage example

This example shows how to set up a workflow route at the `/workflow` endpoint that uses a workflow with the ID `weatherWorkflow`.

```typescript title="src/mastra/index.ts"
import { Mastra } from "@mastra/core";
import { workflowRoute } from "@mastra/ai-sdk";

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      workflowRoute({
        path: "/workflow",
        workflow: "weatherWorkflow",
      }),
    ],
  },
});
```

You can also use dynamic workflow routing based on a `workflowId`. The URL `/workflow/weatherWorkflow` will resolve to the workflow with the ID `weatherWorkflow`.

```typescript title="src/mastra/index.ts"
import { Mastra } from "@mastra/core";
import { workflowRoute } from "@mastra/ai-sdk";

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      workflowRoute({
        path: "/workflow/:workflowId",
      }),
    ],
  },
});
```

## Parameters

<PropertiesTable
  content={[
    {
      name: "path",
      type: "string",
      description: "The route path (e.g., `/workflow` or `/workflow/:workflowId`). Include `:workflowId` for dynamic workflow routing.",
      isOptional: true,
      defaultValue: "'/api/workflows/:workflowId/stream'",
    },
    {
      name: "workflow",
      type: "string",
      description: "Fixed workflow ID when not using dynamic routing.",
      isOptional: true,
      defaultValue: "undefined",
    },
    {
      name: "includeTextStreamParts",
      type: "boolean",
      description: "Whether to include text stream parts in the output.",
      isOptional: true,
      defaultValue: "true",
    },
  ]}
/>

## Additional configuration

You can use [`prepareSendMessagesRequest`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#transport.default-chat-transport.prepare-send-messages-request) to customize the request sent to the workflow route, for example to pass additional configuration to the workflow:

```typescript
const { error, status, sendMessage, messages, regenerate, stop } = useChat({
  transport: new DefaultChatTransport({
    api: "http://localhost:4111/workflow",
    prepareSendMessagesRequest({ messages }) {
      return {
        body: {
          inputData: {
            city: messages[messages.length - 1].parts[0].text,
          },
          // Or resumeData for resuming a suspended workflow
          resumeData: {
            confirmation: messages[messages.length - 1].parts[0].text
          }
        },
      };
    },
  }),
});
```