By API development today is a fragmented, toolchain nightmare. Engineering teams juggle five different platforms—one for design, another for testing, a third for documentation—and now AI agents are supposed to help, but they’re often just bolted on as afterthought copilots. The result? Slower velocity, brittle workflows, and APIs that aren’t architected for AI consumption. The productivity tax is real, and it’s compounding as software scales.
Postman just rebuilt their entire platform from the ground up—not to add AI features, but to make AI native to every layer of the API lifecycle. The shift: Git-native workflows, LLM-ready data models, and Agent Mode operating before the UI even exists.
The Guest: Balaji Raghavan, Head of Engineering at Postman
Key Takeaways
- Postman migrated from Collection JSON to YAML to make APIs diffable, versionable, and consumable by LLMs without hallucination
- Agent Mode now automates unit tests, mocks, specs, and docs—mundane tasks that slow engineering velocity
- Git-native workflows keep API artifacts versioned alongside code, eliminating drift between specs and production
- API catalogs give tech leads real-time visibility into API maturity, governance compliance, and production health
- Postman’s design principle: any new feature must work for Agent Mode before humans can access it in the UI
***
In a recent TFiR interview, Swapnil Bhartiya spoke with Balaji Raghavan, Head of Engineering at Postman, about why his team re-architected their entire platform to make AI a native part of the API development lifecycle—not a bolted-on copilot feature.
Why Postman Re-Architected for AI-Native Workflows
Raghavan explained that Postman had all the components of a complete API platform—exploration, testing, CI/CD integration, and production monitoring—but they were disparate. The core problem wasn’t missing features; it was that the platform wasn’t designed for how AI agents operate.
Q: What drove Postman to rebuild the core platform after being in the market for over a decade?
Balaji Raghavan: “We had these disparate components, but what we also started seeing in the software lifecycle itself is that the exploration process can now be done much faster with AI tools. So rather than just embedding AI tools into the software, we said we have to go back and think about our own APIs from an AI readiness perspective and start building the platform from the ground up.”
He emphasized that bolting AI onto legacy architecture is inefficient. Instead, Postman redesigned their APIs to be natively consumable by LLMs—contextual, descriptive, and structured for agent-driven workflows.
Q: What does “AI readiness” actually mean for API design?
Balaji Raghavan: “Most APIs designed today are not ready for immediate consumption by LLMs. As a result, you need to evolve the APIs your product is built on so they become context-aware and enable LLMs to operate against them without having to refer to large amounts of data and specifications, because you want the operation to be spiffy.”
A core change: migrating from Postman’s legacy Collection JSON format to YAML. This made API definitions diffable in Git, versionable alongside code, and far more digestible for LLMs.
Q: Why did you move from Collection JSON to YAML?
Balaji Raghavan: “A core change we made within the product was to move away from a massive collection JSON object used to describe all of our APIs to a YAML format, which is both diffable and more easily consumable by LLMs. When looking at changes to a single API, you can do so much more efficiently in YAML than in a large JSON object. It also helps the LLM focus on the specific area of change in the API you’re working with, rather than getting confused by all the APIs in the workspace and sometimes hallucinating actions against them.”
Git-Native Workflows and API Artifact Versioning
One of the most significant shifts was moving API artifacts—specs, documentation, tests—out of the cloud and into the code repository itself. This gives developers a single, versioned source of truth for everything related to an API.
Q: Why did you move API artifacts from the cloud to Git repositories?
Balaji Raghavan: “We had to migrate a lot of the content we previously kept in the cloud—including specs and documentation—into the code repository itself. This ensures that when you make changes to the code, the corresponding artifacts are also kept up to date. It gives you a versioned view of all API artifacts, which previously didn’t exist in correlation with your code.”
This eliminates a chronic problem in enterprise API management: drift between production APIs and their documentation. Traditionally, teams share specs via email, Confluence, or SharePoint—a manual, error-prone process. With Git-native workflows, specs live alongside code and update automatically.
Q: How does this change how developers share API specs with customers?
Balaji Raghavan: “You want to make sure the specs customers are working with are up to date with your code. Today, you often have to do that by re-sharing your specs—either over email, through Confluence documents, SharePoint, or other channels—which is inefficient. If the specs are stored alongside your code and published from there, it becomes much easier for customers to consume them.”
Agent Mode: AI-First Development, UI Second
Postman’s Agent Mode is an AI agent that operates across the entire API lifecycle—from design and testing to documentation and monitoring. The radical design principle: any new feature in Postman must work for Agent Mode before humans can use it in the UI.
Q: How did you approach building AI into the product—was it copilot features, or something deeper?
Balaji Raghavan: “By looking at all the core journeys, we redesigned their execution in the backend to ensure that an agent can operate against a cleaner set of APIs that are fully described in natural language, enabling LLMs to use them effectively. That was one of the first principles we followed. The second, which I’m even more proud of, is that we decided any new feature we build must be operable by Agent Mode first, before it’s available in the UI. So even before a human can use a particular capability, we want Agent Mode to be able to operate against it.”
This AI-first approach flips traditional product development. Instead of designing for humans and retrofitting AI, Postman designs for agents and then builds the UI around what the agent can already do.
Q: Why prioritize AI agents over the UI?
Balaji Raghavan: “It’s AI-first thinking, where we don’t bolt AI on after the fact. Instead, we build capabilities for AI to operate first, and only once AI can operate against them do we create a UI for humans. That’s another core area we’ve invested heavily in. Now, almost everything we introduce in Postman starts with availability in Agent Mode.”
This design philosophy extends to background operations—Agent Mode can handle long-running tasks like generating test suites or syncing documentation, freeing developers from manual button-pushing.
Testing Automation: Eliminating the Boring Work
Raghavan emphasized that testing is one of the most tedious, velocity-killing parts of software development. Engineers want to ship features fast, and writing unit tests, mocks, and smoke tests feels like friction. Agent Mode automates all of it.
Q: How does AI change the testing workflow?
Balaji Raghavan: “As an engineer, I can tell you that testing is one of the most boring parts of the job. You want to deploy features more frequently, and testing often gets in the way of your velocity. In some ways, that’s how engineers feel. However, for enterprises, it’s critical to ensure that the systems you’re building are thoroughly tested and will work as intended according to the specifications before deployment. As a result, engineers sometimes take shortcuts—skipping parts of testing or limiting coverage. We take that boring part away. Engineers can now write unit tests, load tests, and smoke tests using AI, and they can do so natively through Agent Mode.”
The result: higher test coverage without slowing down feature velocity. Developers focus on critical thinking and architecture; Agent Mode handles the repetitive execution.
API Catalog: Visibility into API Maturity at Scale
For tech leads and engineering managers, a chronic pain point is lack of visibility into API health and maturity. Postman’s new API Catalog solves this by aggregating data across design, testing, CI/CD, and production—giving leaders a single pane of glass for API governance.
Q: How does the API Catalog help teams manage hundreds of APIs?
Balaji Raghavan: “When you think about API maturity, tech leads and managers within an organization often have no visibility into how mature their APIs are today. To fill that gap, we created an API catalog that allows you to see the evolution of an API—from its development stages to testing stages to production insights. You can then start measuring your critical APIs: How mature are they? Do they have specs that conform to your API style guides and governance rules? Are those rules being enforced every time changes are made to the APIs? We’ve now codified all of this and brought it into the product through our API catalog.”
The catalog isn’t just a dashboard—Agent Mode operates on it, too. If there’s a production outage, the agent can trace the issue back to specific code changes and surface relevant logs.
Q: Can Agent Mode operate on the API Catalog as well?
Balaji Raghavan: “Agent Mode operates on the catalog as well. Within the catalog, I can see the full journey for each codebase—from development to the production endpoints where the code is deployed—and have Agent Mode assist me. If something goes wrong in production, it can help identify which change in the code caused the outage. So Agent Mode doesn’t just operate on API artifacts; it also works with the API catalog. This ensures you’re thinking AI-first not only in the creation and testing of APIs, but also in their management.”
Postman’s Design Principle: Developers Do What Only They Can Do
Raghavan framed the entire re-architecture around a simple philosophy: developers should focus on critical thinking, not button-pushing. Anything that can be automated should be—so engineers spend their time on problems only humans can solve.
Q: What’s the core philosophy behind this AI-native rebuild?
Balaji Raghavan: “Developers want to focus on critical tasks that only they can do—things AI cannot do for them. With that in mind, mundane tasks like writing unit tests, creating API specs, and building mocks for APIs are areas where developers shouldn’t have to click through multiple steps. Instead, we should automate much of this through the agent itself.”
He compared it to his own workflow: if a task doesn’t require mental stimulation or critical thinking, it should be delegated to an agent.
Q: How do you think about what should be automated versus what requires human judgment?
Balaji Raghavan: “I always say this about my own job: I need mental stimulation for at least 50% of the time I’m working. If you start losing that, you almost become just a button pusher. Anything that feels like mere button pushing, I’d rather have an agent handle—doing the repetitive work, summarizing it, and letting me focus on decision-making and the critical thinking where I can add real value.”
What’s Next for AI-Native API Development
Raghavan sees this as the foundation for a new era of developer tooling—one where AI isn’t a feature, but the substrate on which all workflows are built.
Q: Is this the final form, or just the foundation for more AI-native workflows?
Balaji Raghavan: “Evolution continues to happen. This was a big leap forward. Cloud was a big leap, and now AI is an even bigger one, enabling changes in developer workflows. Quantum could be the next major leap, allowing us to do more things in parallel and operate with a much larger context. However, some fundamental problems still exist—such as how we manage memory. For any given operation, you can either rely on the knowledge available in isolation or tap into knowledge from prior instances. Deciding when to use that memory and when not to remains an open, research-oriented problem.”
His long-term vision: a world where non-technical users can build software simply by describing what they need. Engineers, meanwhile, will focus on the architectural and memory management problems that make that possible.
Q: Where do you see this heading in the long term?
Balaji Raghavan: “You might not even need technical skills to solve these problems in the future. Anyone—even my mom—could say, ‘I need an app to solve this problem,’ and AI would go and build it for them. That would be the ideal end state we want to work toward. But if that does happen, the good thing is that engineers will still be the ones building the tools that enable my mom to do that. So the critical thinking around what memory is needed and what context is required to make this possible is something I would be encouraged, as an engineer, to go and solve.”
