The Edge Validates the Origin

On February 12, 2026, Cloudflare published a post titled “Markdown for Agents.” They argued that the web needs a way to serve machine-readable content alongside human-readable HTML. Their solution? A CDN-edge transformation that converts any HTML page into markdown when it sees an Accept: text/markdown header.

We agree with the premise, but we believe the implementation belongs at the origin.

While generic HTML-to-markdown conversion is a great fallback for legacy sites, API documentation is different. It is structured, technical, and highly sensitive to token limits. SWAGENT v0.1.6 brings this capability directly to your API origin, serving purpose-built documentation generated from your OpenAPI specs.

Content Negotiation Explained

Content negotiation is a core part of the HTTP spec that we have mostly ignored for a decade. We used it for JSON vs XML, and then we just settled on JSON. But AI agents change the requirements.

When a browser hits your API root, it wants HTML. When an AI agent hits it, it wants a compact, token-optimized representation of your capabilities.

With SWAGENT v0.1.6, you don’t need separate URLs. The same endpoint handles both:

# Browser gets HTML
curl https://api.example.com/

# AI agent gets token-optimized docs
curl -H "Accept: text/markdown" https://api.example.com/

Standard HTTP. Same URL. Different representation.

The “Tell Your AI Agent” UX

We often talk about “developer experience,” but we are entering the era of “Agent Experience” (AX). You should not have to tell your users to “go to our docs, find the llms.txt link, and paste it into your prompt.”

The real UX is simpler. You tell your user: “Tell your AI agent: Learn https://api.example.com.”

The agent performs a GET request. It includes Accept: text/markdown because it prefers structured text over messy HTML. Your API responds with the SWAGENT-optimized markdown. The agent learns your API in seconds, using 70% fewer tokens than if it had to parse a Swagger UI page.

Token Estimation via HEAD

AI agents are cost-conscious. Before downloading a massive documentation file, an agent might want to know how much it will cost to process.

SWAGENT v0.1.6 implements the x-markdown-tokens header. By sending a HEAD request with the correct Accept header, an agent can get an exact token count before committing to the full download.

# Check token count before downloading
curl -I -H "Accept: text/markdown" https://api.example.com/
# x-markdown-tokens: 1842

This is built on the estimateTokens utility from @swagent/core, ensuring accuracy across different model tokenizers.

Production-Ready Caching

Serving different content at the same URL can be a nightmare for CDNs if not handled correctly. SWAGENT handles this by automatically setting the Vary: accept header.

This tells Cloudflare, Akamai, or your local Nginx cache that the response depends on the Accept header. The HTML version and the Markdown version are cached as separate entities. We also generate unique ETags for each variant, ensuring that a change in your OpenAPI spec triggers a cache bust for both representations simultaneously.

Route Table Evolution

Before v0.1.6, you had to manage a specific route for your AI docs. It usually looked like this:

Path	Purpose
/	API Root / Welcome
/docs	Swagger UI
/openapi.json	Raw Spec
/llms.txt	AI Documentation

After v0.1.6, the AI documentation is “invisible” to humans but discoverable by machines. Your route table stays clean, but your capabilities expand:

Path	Accept: text/html	Accept: text/markdown
/	Welcome Page	AI Documentation
/docs	Swagger UI	AI Documentation

How to Get It

If you are using one of our official adapters, v0.1.6 enables content negotiation by default. You just need to register the plugin and provide your base URL.

import { swagentFastify } from '@swagent/fastify';

app.register(swagentFastify, {
  baseUrl: 'https://api.example.com'
});
// That's it. Content negotiation is built in.

SWAGENT handles the header detection, the Vary headers, the token estimation, and the markdown generation.

SWAGENT vs Cloudflare

It is worth noting the difference in philosophy. Cloudflare’s approach is generic. It takes whatever is on the page and tries to make it readable. It is a “brute force” solution for the entire web.

SWAGENT is a “precision” tool for APIs. We don’t just strip HTML tags. We transform OpenAPI definitions into a compact notation with inline types and authentication shorthands designed specifically for LLM context windows.

The best part? They are complementary. You can run SWAGENT at your origin and let Cloudflare handle the edge delivery.

Try the Interactive Playground →