Dev48
Language
  • About
  • Services
  • Industries
  • Technologies
  • Articles
  • Contacts
Book a call
    Home/Articles/Build a developer portal with postman and fern in a day
Dev48
info@dev48.org+375 29 320-40-96WhatsApp@isky_by

© 2026 · All rights reserved.

Build a Developer Portal with Postman and Fern in a Day

Фото: GLady (Pixabay) — https://pixabay.com/photos/butterfly-insect-animal-44882/

Source: Postman Blog•November 17, 2026 at 04:11 PM

Build a Developer Portal with Postman and Fern in a Day

Learn how to build a developer portal with Postman and Fern using Git-backed Collections and MDX. Ship docs in a day without SaaS fees or front-end work. The post Build a Developer Portal with Postman and Fern in a Day appeared first on Postman Blog .

November 17, 2026

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 on one tool for all of it so heavily 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 diagram shows the high-level architecture. 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. This is what came out in about an hour: 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 .mdx files under root/fern/docs/pages. Each file is a page on your new developer portal.
  • Let your agent modify these .mdx files.

An .mdx file mixes Markdown, JavaScript, and CSS. Here is an example:

The image above shows how the .mdx files, written by you or your favorite LLM, map to the resulting pages. Place them 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.txt and /llms-full.txt at the root, generated automatically alongside robots.txt and sitemap.xml. llms.txt is a compact index, and llms-full.txt embeds the full content. Appending /llms.txt to any page URL gives a page-level index.
  • Markdown for every page. Append .md to 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 with mcp: 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.txt still 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

  • Postman Git-backed API projects
  • Fern documentation
  • Postman Agent Mode
  • JSON Jet Developer Portal demo
  • MDX documentation
← All articles

What this article says

More in Software Development

All →
Ray Train: Diagnosing GPU Starvation in Model Training with Data Ingest Observability
Anyscale

Ray Train: Diagnosing GPU Starvation in Model Training with Data Ingest Observability

Same Wrong Answer, Different Reasons: Why Student Thinking Matters.
Khan Academy

Same Wrong Answer, Different Reasons: Why Student Thinking Matters.

Help Your Team Code Faster and Explore Further with Kilo Desktop
Anaconda

Help Your Team Code Faster and Explore Further with Kilo Desktop

Teladoc Health Expands Comprehensive Weight Care Program with Employer Contribution Option for GLP-1 Medications
Teladoc Health

Teladoc Health Expands Comprehensive Weight Care Program with Employer Contribution Option for GLP-1 Medications

L3Harris and Partners Demonstrate Multi-Domain Capabilities at EVEREST: Pacific Vigilance
L3Harris

L3Harris and Partners Demonstrate Multi-Domain Capabilities at EVEREST: Pacific Vigilance

Add interactivity to Canva presentations with Kahoot! 360
Kahoot

Add interactivity to Canva presentations with Kahoot! 360

More from Postman

Fern is now Postman’s home for API Dev Portals
Postman

Fern is now Postman’s home for API Dev Portals

What’s new in Postman: Kafka, MCP tests, RAML
Postman

What’s new in Postman: Kafka, MCP tests, RAML

Sharing API Simulations Across Coding Agent Sessions
Postman

Sharing API Simulations Across Coding Agent Sessions

One Terminal, Entire Agentic SDLC: Live Nov 17 at 10 AM PST
Postman

One Terminal, Entire Agentic SDLC: Live Nov 17 at 10 AM PST

Handling a leaked credential with the Postman plugin
Postman

Handling a leaked credential with the Postman plugin

How to migrate JMeter tests to Postman
Postman

How to migrate JMeter tests to Postman