Originally published on the Postman blog.
How to turn Postman Collections into a Fern portal with an agent. If your APIs already live in Postman, you may be closer to a real developer portal than your backlog suggests. This walkthrough drives the whole build through a coding agent. You get Git-backed .mdx pages, and the same build serves agents as well as humans through /llms.txt and .md endpoints. You don't need a front-end sprint to get there.
As a former API Platform Lead and Product Owner, I know how much an API developer portal matters. It is more than a showcase for your APIs. A good portal does a lot of work across the organization:
- It documents your API and makes it easier for other developers to discover and integrate, especially when you back it with SDKs and code examples.
- It speeds up internal and external onboarding, with contact forms, self-service API keys, and guided onboarding flows.
- It notifies developers about API changes, from new versions to breaking changes.
- It gives developers and business analysts a single source of knowledge, which matters more as internal turnover increases.
- It makes your API products tangible for non-technical stakeholders and budget owners, who often have no other way to experience what the team is building.
- It advertises your company to technical B2B partners. Developers can tell at a glance whether an API program is a priority just by looking at the portal.
A portal can also take on other roles: an internal testing surface for manual testers, a monitoring tool where partners check their usage and quota, and a support dashboard for customers who contact you through the platform.
I learned the hard way that a developer portal needs dedicated budget and capacity. That capacity usually only appears when the pressure to ship new APIs is low. To put it bluntly, budget owners almost always rate a new API above a new website page, so the portal and the APIs end up competing for the same team capacity.
It does not have to be that way. Besides pulling your own people into front-end work, the other option has always been a dedicated SaaS solution. It works as a central CMS for the portal, but it needs procurement, onboarding, and very high license fees, and someone still has to maintain it. Spending 100k per year on a developer portal, and keeping people busy maintaining it instead of building APIs, never sat right with me. We did not do that.
As an API platform team, we supported the complete API lifecycle, from ideation and design to implementation, testing, and maintenance, both internally and for external customers. We already relied so heavily on one tool for all of it that we did not think of it as the third option. Postman was our source of truth for collaboration, from design to test, for producing APIs and consuming them. Using it for documentation turned out to be the most efficient way to build a showcase for our APIs without changing the tech stack much. That is even more true since Postman acquired Fern. Fern sits on top of existing Postman Collections and generates developer portals you can customize heavily, even as a non-developer. (Full disclosure: I work at Postman.)
Let me walk you through what I think is the most efficient way to build a developer portal, using technology your company most likely already has. It adds no new software. You use what you already own more efficiently, together with Fern.
The high-level architecture is simple. Your API team stays on the APIs, and you do not need an expensive SaaS solution. Postman most likely already sits on top of your existing Git-backed API project. Fern takes the existing Collections and specs, adds .mdx files for visuals, and publishes everything on a URL you can map to your own domain.
I imagined a fictional airline called JSON Jet Airways and asked Claude to do its best on the visuals. In about an hour, it produced the visuals for the JSON Jet Developer Portal.
How I built it
I drove almost all of this through a coding agent instead of clicking through the UI. Here is the path:
- Connect your coding agent to Postman with the Postman plugin.
- Ask the agent to create a Public Workspace with the Git integration.
- Have the agent update the Collection and Workspace documentation.
- Let the agent publish the developer portal to Fern automatically for you.
- Register with Fern (free to start). A GitHub repo gets created. Take ownership of this repo in the Fern dashboard.
- Clone the repo and work with the Fern CLI, which I use daily.
- Inside the repo, you will find
.mdxfiles underroot/fern/docs/pages. Each file is a page on your new developer portal. - Let your agent modify these
.mdxfiles.
An .mdx file mixes Markdown, JavaScript, and CSS. Here is an example:
---
title: My Post
description: A short demo of MDX
---
import { useState } from "react"
# Regular markdown works here
You can write **normal markdown** and drop in live JSX whenever you need it.
export function Counter() {
const [count, setCount] = useState(0)
return (
<button onClick={() => setCount(count + 1)}>
Clicked {count} times
</button>
)
}
<Counter />
Each .mdx file, written by you or your favorite LLM, maps to a page of the portal. Place the files in the repository and connect them through a nav bar. That is all there is to it.
The longest part was waiting for Claude to finish the .mdx files. I also added front-end tests for the portal with Playwright, but that is a topic for another post.
What this solves
- The whole team gets access through Git and Postman Workspaces. Everyone who publishes content to the portal already knows Git.
- The portal needs no dedicated owner, so your API team can stay on the APIs.
- There is no dedicated front-end work and no $100k+ SaaS budget competing with your API roadmap.
- You get a fully functioning developer portal within one day.
- A Git-based workflow makes it easy to add CI/CD, branching, and automated tests later. Portal updates can live in the same workflow as your API changes, so the docs do not lag behind.
One portal, two audiences: humans and AI agents
There is one more reason this setup held up over time. Humans are no longer the only readers of developer portals. Coding agents, RAG pipelines, and in-IDE assistants hit docs sites constantly, and most portals were not designed for that traffic. Fern was. The site you just built for your team already serves AI agents well, with no extra work from you.
Fern does a few things out of the box:
-
Machine-readable entry points. Every site gets
/llms.txtand/llms-full.txtat the root, generated automatically alongsiderobots.txtandsitemap.xml.llms.txtis a compact index, andllms-full.txtembeds the full content. Appending/llms.txtto any page URL gives a page-level index. -
Markdown for every page. Append
.mdto any page URL and you get clean Markdown back, with no HTML scraping and no navigation clutter. - Markdown for bots. When Fern detects an LLM bot, it serves Markdown instead of HTML. Fern reports this cuts token use by 90% or more, which matters when agents pay per token to read your docs.
-
Content tags for agent-specific output.
<llms-only>shows content only to AI tools,<llms-ignore>hides content from them, and query parameters can filter output further, for example by SDK language. - Ask Fern, a RAG chat with citations. It runs in your docs, in Slack, and through an API you can embed in your own product.
-
A hosted MCP server per docs site. Any site with Ask Fern enabled gets an MCP server at
/_mcp/server, and Claude Code, Cursor, and Windsurf can connect to it with one click. For authenticated sites, Fern recommends turning it off withmcp: false. - Access to protected docs. Agents can get a JWT using a Fern API key, so they can read gated content and use search without bypassing your auth.
-
Crawl and training control. Your own
robots.txtstill decides whether third-party tools can crawl or train on the content.
For internal tools, you can also install a private MCP server scoped to your org (fern mcp install). It gives coding agents context on docs.yml, components, and CLI commands. Fern Agent can edit docs, open PRs, and run on a schedule or from a Slack flow.
The same .mdx files that power your portal for humans are also how every coding agent your partners and customers use will discover your API. You get both audiences from one build.
I wish someone had shown me this approach years ago, and I hope it reaches you sooner. It is an efficient way to show your work to internal colleagues and the outside world without pulling your team away from what they are there to build: the APIs.
Resources
The original post links to the Publish to Fern integration, Postman Git-backed API projects, the Fern documentation, Postman Agent Mode, the JSON Jet Developer Portal demo and the MDX documentation. Read the full walkthrough on the Postman blog and build your own developer portal from the Postman Collections you already have.
Have you shipped a portal from existing Collections, or are you still stuck choosing between the portal and the API roadmap? Questions about the setup are welcome in the comments.
Top comments (1)
One useful guard is to validate generated examples and schema responses against the same versioned API contract in CI; that catches a portal that builds cleanly but quietly drifts from what developers will actually call.