Flows Best Practices with Postman

API development encompasses more than building and maintaining endpoints. Consumers—which today include developers, testers, partners, and AI agents—must be able to discover, understand, and integrate with those APIs reliably. Flows is designed to support that requirement.

Flows is built on top of collections. It provides a visual execution environment for composing API request sequences, transforming data, and modeling conditional workflow logic.

Flows capabilities

Capability	Description	What it does
Infinite Canvas	An unbounded workspace for designing and visualizing API workflows	Lets you freely arrange, zoom, and navigate complex workflows, without the constraints of a fixed viewport or rigid layout. This makes it practical to model both simple request chains and large, multi-step systems within a single shared canvas.
Modular Flows	Reusable workflow logic you can share across multiple Flows without duplicating or maintaining redundant scripts	Helps teams enforce consistency across workflows and reduces the overhead of keeping shared logic in sync as APIs evolve.
Grouping and Organization	Annotated canvas sections that create a guided, step-by-step walkthrough of your workflow logic	Simplifies and reduces the time it takes to onboard new team members or walk partners through how a workflow operates.
Live Embeds	Ability to share or embed a visual representation of your workflow directly into internal or external documentation	Gives API consumers a live, accurate view of how your APIs are structured without leaving their documentation context.
Test Scenarios	Ability to define and test a wide range of inputs without maintaining separate workflows	Enables you to use environmental variable values directly to validate behavior across conditions, as well as cover edge cases.
Run Logs	Ability to execute and trace visual workflows step by step, providing visibility into inputs, outputs, and state at every stage of execution	Makes it easier to debug failures, validate behavior, and understand how data moves through a workflow.

Flows for documentation

Documentation about individual API calls rarely tells the whole story. To solve a real-world problem, developers need to understand how a series of endpoints work together, and static text pages struggle to convey that clearly. Flows addresses this by turning documentation into an executable, interactive workflow that anyone can run and explore directly.

Use Grouping and Organization to annotate and structure sections of the canvas, creating a guided walkthrough of the workflow logic for readers unfamiliar with the system.

Once your Flow is ready, Live Embeds let you bring that visual representation into your existing documentation. You can embed a Flow directly into your docs pages, giving readers a runnable illustration of the workflow alongside your written content. If you maintain a Public API on the Postman API Network, you can add a live embed to your Public API Network page so developers discovering your API for the first time immediately see how it works in practice, not just what the endpoints are.

Flows for API testing

Postman supports two approaches to API testing: collection-based tests using the collection runner, and visual workflow tests using Flows. Use Flows when your testing requires conditional logic, branching, or a clear visualization of a multi-step transaction. Flows is also a good choice for teams that include less technical contributors, since tests can be built, reviewed, and modified without scripting.

To test complex, end-to-end scenarios, use built-in blocks to define decision logic based on API responses, and use Test Scenarios to validate behavior across a range of inputs without maintaining separate workflows. This makes Flows well suited for validating the logic of a complete workflow, particularly when the sequence of calls changes based on the data returned.

To incorporate AI into your testing, use the Agent block to add flexibility to your workflow logic, or use Agent Mode to generate test Flows automatically. Point Agent Mode at your collection and it will build the workflow for you, ready to run and iterate on.

To run Flows as part of a CI/CD pipeline, you have two options. With an Enterprise license, you can use the Postman CLI to run Flows directly, including against APIs in a private network. Without an Enterprise license, you can create a request from a deployed Flow, add it to a collection, and run it through the collection runner using the Postman CLI.

Flows for AI-ready APIs

AI agents and LLMs place different demands on APIs than human developers do. They require consistent naming conventions, predictable response schemas, and well-structured error handling to function reliably. Without these, agents are prone to misinterpreting responses or failing silently. Flows lets you wrap your existing APIs to enforce these requirements without modifying the underlying endpoints.

Specifically, you can use Flows to:

Normalize response envelopes so every response follows a consistent structure, such as always wrapping data in a data field with a predictable shape
Coerce data types to ensure fields like dates, booleans, or numeric identifiers are always returned in the expected format
Filter or remap response fields to remove noise or inconsistency before the agent receives them
Flatten nested structures that would otherwise require an agent to traverse unpredictably
Normalize null handling, for example ensuring empty collections always return an empty array rather than null or an omitted field

This gives you control over how agents and users interact with your APIs, shaping both how endpoints are called and what their responses look like.

Once you are satisfied with the augmented API, you can deploy your Flow as an MCP server. This exposes your workflow as a structured interface that LLMs can call directly, enabling agent-driven consumption of your APIs without requiring changes to your existing infrastructure.

Flows for collaboration

API collaboration typically involves sharing collections, specifications, and documentation links, leaving consumers to piece together how individual endpoints work together. Flows replaces this with a single executable artifact that demonstrates a complete business process alongside the collections your team has already curated. Whether collaborating within an internal workspace or sharing externally via a public or partner workspace, Flows gives every stakeholder a clear, runnable picture of how APIs work together. If a collaborator has a question about how a workflow is structured, Agent Mode can answer it in natural language without requiring them to dig through documentation.

Flows can also be versioned alongside your API code using the Postman Local view. You can pull your Flows from the cloud into a local git-synced folder, keeping them up to date with your codebase whether through the Postman UI or with AI assistance in your IDE. When teammates clone the repository, they can run your Flows immediately without needing to locate the correct workspace.

Flows for onboarding

Flows reduce the time it takes for new team members to learn unfamiliar systems by making API workflows executable and explorable. Instead of reading static documentation, a developer can open a Flow, run it, and immediately observe the sequence of calls and the data moving between them.

Use Grouping and Organization to annotate and structure the canvas so that the workflow serves as a guided introduction to the system. Include Test Scenarios to let new developers safely experiment with edge cases and error conditions. Because Test Scenarios integrate directly with your Postman environments and vault, developers can run against a development or staging environment without affecting production data.

Agent Mode extends this further by letting developers ask questions about any Flow in natural language. They can ask what a specific step does, how data moves between blocks, or why a particular path is taken, and get an immediate answer without needing to locate and parse separate documentation.

Getting started with Flows

Create a new Flow: In your Postman workspace, select Flows from the sidebar. Click the + button or Create Flow to open a new, blank canvas with a Start block already in place.
Add your first block: Right-click anywhere on the canvas to add a block. A common first step is to add a request from one of your existing collections.
Connect the blocks: Hover over the output port on the right side of a block and drag the connection line to the input port on the left side of the next block to create a sequence.
Run the Flow: Click the Run button at the bottom of the canvas. The Flow will execute and live data will appear below each block as it runs. For a more detailed view, open the Run panel, which provides a structured step-by-step breakdown of the execution as well as a searchable raw console log.

Key outcomes

When you apply the practices in this guide, you achieve three critical business outcomes:

Faster onboarding and fewer repeated questions: By making workflows easy to see and execute, new team members and partners can better understand the workflow without having to pull in the original author every time.
Consistent, AI-ready API behavior: By using Flows as an adapter layer, you can control what agents see and how responses are shaped.
Living documentation: By versioning Flows alongside your code and embedding them in your docs, your documentation stays up to date as your API changes.

Ready to get hands-on? Learn more about Postman Flows →