Guides
Get content negotiation right.
Practical patterns for shipping content negotiation correctly.
Fundamentals
- What content negotiation is One URL, many representations. The server picks which bytes to send based on the client's
Acceptheader. - Why Serve Markdown First for AI Agents Fewer tokens, higher retrieval signal, faster responses. Three reasons AI agents prefer Markdown over the HTML you'd send a browser.
- The Accept: text/markdown convention What AI agent clients send, what your server should match on, and the exact media-type string defined by RFC 7763.
- Cloudflare — Markdown for Agents If your site sits behind Cloudflare, flipping this one toggle negotiates Markdown at the edge with no origin changes required.
Getting it right
- Set the Vary: Accept header Without
Vary: Accept, CDNs and browser caches will happily serve the wrong representation to the wrong audience. - Parsing Accept & quality values Ranking types by q-value, breaking ties by specificity, and respecting
q=0. The parsing rules every content-negotiating server needs to get right. - Returning 406 Not Acceptable When an
Acceptheader genuinely can't be satisfied,406is the right response. The common mistake is returning it too eagerly. - Caching & CDN setup
Vary: Acceptis necessary but not always sufficient. Cloudflare, Fastly, and Vercel each have quirks you need to know before production.