# Return text/markdown via Content Negotiation

> Return text/markdown when an agent sends Accept: text/markdown, so one canonical URL serves humans and machines the right format via HTTP.

## What content negotiation is

Content negotiation is the standard HTTP mechanism where the server picks a response representation based on the client's `Accept` request header. For the agentic web: when an agent sends `Accept: text/markdown`, you return the Markdown version; when a browser sends `Accept: text/html`, you return HTML. One canonical URL, two representations — no separate `.md` link required. The media type `text/markdown` is registered with IANA.

## Why it matters for agents

Markdown twins solve the format problem at a second URL; content negotiation solves it at the *same* URL the human uses, keeping your canonical, analytics, and link equity on one address. An agent simply asks for the format it wants and gets it, the way the HTTP spec always intended. It is the cleanest expression of the content dimension's goal: serve the right format to the right client without duplicating addresses.

## How to implement it

1. At your server or edge layer, inspect the `Accept` header on each request.
2. When it includes `text/markdown`, respond with the Markdown body and `Content-Type: text/markdown`; otherwise serve HTML. Send `Vary: Accept` so caches store both variants correctly.
3. Verify: `curl -H "Accept: text/markdown" https://yoursite/page` returns Markdown with the right `Content-Type`, while a normal request still returns HTML.

This satisfies the audit check `content.content_negotiation` (pass: a request with `Accept: text/markdown` returns a `text/markdown` body at the canonical URL). You can request this very page with `Accept: text/markdown` as live proof. Confirm the `text/markdown` media type against the IANA registry at build, then verify the result with the Agent-Readiness Audit.

Related: [the content dimension](/agent-readiness/content) · [markdown twins](/agent-readiness/markdown-twins) · [the Agentic Web Lexicon](/glossary) · [audit your site](/services)