Skip to content

Markdown for Agents

Last updated View as MarkdownAgent setup

What is Markdown for Agents

Markdown has quickly become the lingua franca for agents and AI systems as a whole. The format’s explicit structure makes it ideal for AI processing, ultimately resulting in better results while minimizing token waste.

Cloudflare's network supports real-time content conversion at the source, for enabled zones using content negotiation ↗︎ headers. When AI systems request pages from any website that uses Cloudflare and has Markdown for Agents enabled, they can express the preference for text/markdown in the request and our network will automatically and efficiently convert the HTML to Markdown, when possible, on the fly.

Read the announcement ↗︎ in our blog for more information.

How to use

To fetch the Markdown version of any page from a zone with Markdown for Agents enabled, the client needs to add the Accept negotiation header with text/markdown as one of the options. Cloudflare will detect this, fetch the original HTML version from the origin, and convert it to Markdown before serving it to the client.

Here's a curl example with the Accept negotiation header requesting this page from our developer documentation:

curl https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/ \
  -H "Accept: text/markdown"

Or if you’re building an AI Agent using Workers, you can use TypeScript:

const r = await fetch(
	`https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/`,
	{
		headers: {
			Accept: "text/markdown",
		},
	},
);
const markdown = await r.text();
const r = await fetch(
	`https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/`,
	{
		headers: {
			Accept: "text/markdown",
		},
	},
);
const markdown = await r.text();

The response to this request is now formatting in markdown:

HTTP/2 200
date: Wed, 11 Feb 2026 11:44:48 GMT
content-type: text/markdown; charset=utf-8
vary: accept
cache-control: public, max-age=3600
strict-transport-security: max-age=63072000; includeSubDomains
content-signal: ai-train=yes, search=yes, ai-input=yes

---
title: Markdown for Agents · Cloudflare Agents docs
---

## What is Markdown for Agents

Markdown has quickly become the lingua franca for agents and AI systems
as a whole. The format’s explicit structure makes it ideal for AI processing,
ultimately resulting in better results while minimizing token waste.
...

Response headers

Markdown for Agents preserves the headers from your origin response on the converted response, so security- and cache-relevant headers survive conversion. This includes headers such as Strict-Transport-Security (HSTS), Content-Security-Policy (CSP), X-Frame-Options, Set-Cookie, CORS headers (for example, Access-Control-Allow-Origin), and caching headers (Cache-Control, Expires, Age).

Because the body is replaced with converted Markdown, the following changes are applied:

  • Content-Type is set to text/markdown; charset=utf-8.
  • Vary includes Accept (any Vary dimensions your origin already declared are preserved) so that caches store separate variants for Markdown and HTML.
  • Content-Length is removed because the Markdown response is streamed.
  • Headers that describe the original body are removed, because they no longer match the converted response: Content-Encoding, Content-Range, Transfer-Encoding, ETag, and Last-Modified. ETag and Last-Modified are dropped because conditional requests (If-None-Match, If-Modified-Since) cannot be honored for converted responses.

Content Signals Policy

Content Signals ↗︎ is a framework that allows anyone to express their preferences for how their content can be used after it has been accessed.

If your origin already sets a content-signal header, Markdown for Agents preserves that value on the converted response — your origin's policy is authoritative. This lets you define custom Content Signal policies by setting the content-signal header at your origin.

When the origin response does not include a content-signal header, Markdown for Agents adds a default Content-Signal: ai-train=yes, search=yes, ai-input=yes, signaling that the content can be used for AI Training, Search results, and AI Input, which includes agentic use.

Output format

Markdown for Agents returns a Markdown document with a consistent, predictable structure so AI systems can rely on it without per-site parsing logic. The response always follows this layout:

  1. YAML frontmatter with metadata extracted from the page's <meta> tags. Only emitted when at least one supported meta tag is present.
  2. Body Markdown converted from the document body. Non-content elements (such as headers, footers, navigation, scripts, and styles) are stripped during pre-processing. For the full list of elements that are removed, refer to HTML pre-processing in the Workers AI Markdown Conversion documentation.
  3. JSON-LD structured data preserved as a fenced json code block at the end of the document. Only emitted when the source HTML contains JSON-LD.

YAML frontmatter

When the source HTML contains supported <meta> tags, Markdown for Agents prepends a YAML frontmatter block to the response. The block uses the following fields:

Field Source <meta> tag
title <meta name="title">, with fallback to <meta property="og:title">
description <meta name="description">, with fallback to <meta property="og:description">
image <meta property="og:image">

Only fields with a value are emitted. If the source HTML does not contain any of the supported meta tags, the frontmatter block is omitted entirely.

For title and description, the standard <meta name="..."> form always takes priority over the Open Graph <meta property="og:..."> form, regardless of the order they appear in the HTML. Open Graph values are used only as fallbacks when the standard form is missing.

Example output:

---
title: My Page Title
description: A short summary of the page.
image: https://example.com/cover.png
---

# Page heading

...

JSON-LD

JSON-LD ↗︎ is a structured-data format used by search engines and AI systems to interpret a page's semantic content. Markdown for Agents preserves any <script type="application/ld+json"> blocks from the source HTML by appending them at the end of the converted Markdown inside a single fenced json code block.

If the source HTML contains multiple JSON-LD scripts, all of them are concatenated within the same code block, each on its own line.

JSON-LD is the only <script> content preserved in the output — all other <script> and <style> content is stripped during HTML pre-processing.

Example output:

... main markdown content ...

```json
{
	"@context": "https://schema.org",
	"@type": "Article",
	"headline": "Article Title",
	"author": { "@type": "Person", "name": "Jane Doe" }
}
```

How to enable

To enable Markdown for Agents for your zone in the dashboard:

  1. In the Cloudflare dashboard, select your zone and go to Agent Readiness > Markdown for Agents.

    Go to Markdown for Agents ↗
  2. Turn on Serve Markdown to AI agents. You need permission to edit zone settings and a supported plan.

Enable for specific subdomains or paths

To enable Markdown for Agents for specific subdomains or paths instead of your entire zone, create a configuration rule:

  1. Log in to the Cloudflare dashboard ↗︎ and select your account.
  2. Select the zone you want to configure.
  3. Go to Rules > Overview and select Create rule > Configuration Rules.
  4. Under When incoming requests match, build an expression to match your subdomain (for example, http.host eq "docs.example.com") or path.
  5. Under Then the settings are, select Add setting > Markdown for Agents and set it to On.
  6. Select Deploy.

To enable Markdown for Agents for your zone using APIs, send a PATCH to /client/v4/zones/{zone_tag}/settings/content_converter with the payload {"value": "on"} to the Cloudflare API.

You will need to create an API token with the Zone Settings edit permissions enabled.

Example:

Enable Markdown for Agentsbash
curl -X PATCH 'https://api.cloudflare.com/client/v4/zones/{zone_tag}/settings/content_converter' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer {api_token}" --data-raw '{"value": "on"}'

Enable for specific subdomains or paths

To enable Markdown for Agents for specific subdomains or paths instead of your entire zone, create a configuration rule:

Enable Markdown for Agents for a subdomainbash
curl --request PUT \
  --url "https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_config_settings/entrypoint" \
  --header "Authorization: Bearer {api_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "rules": [{
      "expression": "http.host eq \"docs.example.com\"",
      "action": "set_config",
      "action_parameters": {
        "content_converter": true
      },
      "description": "Enable Markdown for Agents for docs subdomain"
    }]
  }'

You can also use path-based expressions like starts_with(http.request.uri.path, "/blog/"). For more information on building expressions, refer to Rules language.

If you are using Cloudflare for SaaS and want to enable Markdown for Agents for your custom hostnames, you have two options:

Enable for all custom hostnames

To enable Markdown for Agents for all custom hostnames on your SaaS zone:

  1. Log into the Cloudflare dashboard ↗︎ and select your account.
  2. Select your SaaS zone.
  3. Look for Quick Actions.
  4. Toggle the Markdown for Agents button to enable.

Enable for specific custom hostnames

Enabling Markdown for Agents for specific custom hostnames requires an advanced subscription with access to custom metadata.

Step 1: Set custom metadata on the custom hostname

When creating or updating a custom hostname via API, add content_converter to the custom_metadata object:

curl --request PATCH \
  --url "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
  --header "Authorization: Bearer {api_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "custom_metadata": {
      "content_converter": "enabled"
    }
  }'

Step 2: Create a Configuration Rule

Create a Configuration Rule on your SaaS zone that matches custom hostnames with the metadata and enables content conversion:

curl --request PUT \
  --url "https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_config_settings/entrypoint" \
  --header "Authorization: Bearer {api_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "rules": [{
      "expression": "lookup_json_string(cf.hostname.metadata, \"content_converter\") eq \"enabled\"",
      "action": "set_config",
      "action_parameters": {
        "content_converter": true
      },
      "description": "Enable content converter for opted-in custom hostnames"
    }]
  }'

This will enable the feature on custom hostnames that have the content_converter custom metadata tag set.

Analytics

Use the dashboard or the GraphQL Analytics API to monitor conversions, estimate token savings, and diagnose partial or failed conversions.

Dashboard

In the Cloudflare dashboard, select your zone and go to Agent Readiness > Markdown for Agents.

Go to Markdown for Agents ↗

Use the hostname selector and time range to narrow analytics and logs. The page provides Analytics, Logs, and Playground tabs.

Analytics

The Analytics tab shows conversion attempts, full conversion rate, estimated token reduction, partial conversions, and unfinished or failed conversions.

Markdown for Agents dashboard showing conversion totals, full conversion rate, estimated token reduction, and conversions over time.

Use the charts and breakdowns to inspect conversions:

  • Conversions over time
  • Top converted pages
  • Top user agents
  • Failure reasons
  • Content limits
  • Top pages not converted

Top pages not converted includes pages with partial or failed conversions. Content limits identifies conversions with truncated input, omitted front matter, or omitted JSON-LD. A conversion can reach more than one limit.

Logs

The Logs tab shows sampled conversion events with page URLs, user agents, outcomes, failure reasons, and content limits. Filter by outcome, failure reason, or content limit to investigate issues.

Each row represents an estimated request count, not necessarily one request.

Playground

The Playground tab tests a path with Accept: text/markdown and compares the response with HTML. Inspect Markdown, a rendered preview, response headers, and estimated token reduction.

Playground uses the selected hostname, or the zone apex when All hostnames is selected. If your browser cannot read the response because of cross-origin resource sharing (CORS) restrictions or a network error, use the provided curl command.

GraphQL Analytics API

Query the markdownForAgentsAdaptiveGroups dataset under viewer.zones for one zone or viewer.accounts for an account. Use an API token with Analytics Read access scoped to the resources you query.

The dataset is available on all plans. Analytics access does not turn on conversion or change conversion availability.

Queries cover up to seven days of history, with a maximum seven-day query window and 1,000 groups per dataset query.

For example, this query returns conversion totals and the top pages by estimated conversion attempts for a zone:

query MarkdownForAgents($zoneTag: string, $start: Time, $end: Time) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			totals: markdownForAgentsAdaptiveGroups(
				limit: 1
				filter: { datetime_geq: $start, datetime_lt: $end }
			) {
				count
				sum {
					fullRequests
					partialRequests
					completedUnknownRequests
					failedRequests
					unfinishedRequests
					savingsInputTokens
					savingsOutputTokens
					estimatedTokensSaved
				}
			}
			pages: markdownForAgentsAdaptiveGroups(
				limit: 10
				filter: { datetime_geq: $start, datetime_lt: $end }
				orderBy: [count_DESC]
			) {
				count
				dimensions {
					pageUrl
				}
			}
		}
	}
}

Set zoneTag to your zone ID. Set start and end to UTC timestamps within the last seven days. For instructions on submitting the query and variables, refer to Querying basics.

Group or filter results with dimensions such as hostname, pageUrl, userAgent, outcome, and errorCode. The inputStatus, frontmatterStatus, and jsonLdStatus dimensions identify content limits. Account-scoped queries also support the zoneTag dimension.

Interpret analytics

Analytics and logs use sampled conversion attempts. Counts and token sums are sample-weighted estimates, excluding skipped requests and some early cancellations.

User agents are client-supplied strings, not verified bot identities. Page URLs exclude query strings, fragments, and credentials.

Conversion outcomes distinguish the following results:

Outcome Meaning
full Conversion completed with all content-limit flags known to be false. This does not mean lossless HTML preservation.
partial Conversion completed, but a content limit truncated the input or omitted front matter or JSON-LD.
completed_unknown Conversion completed, but limit information cannot establish whether output was full or partial.
error Conversion ended with a terminal error. Inspect errorCode for the failure reason.
unfinished The stream did not reach a terminal conversion outcome. The cause is unknown.

Token estimates use bytes divided by four, rounded down, rather than a tokenizer. Savings include only full conversions with a positive input token estimate.

Partial, failed, unfinished, and unverified conversions do not contribute to savings. estimatedTokensSaved is signed: Markdown larger than its HTML input contributes a negative value.

Calculate token reduction as 1 - savingsOutputTokens / savingsInputTokens when savingsInputTokens is greater than zero. Completion and output token estimates do not prove delivery to the client.

Cloudflare Traces

Cloudflare Traces records Markdown conversion within the request timeline. When tracing is enabled and a request is sampled, a streaming conversion adds a markdown_conversion span under response. Skipped conversions and HEAD responses do not create this span.

To capture and inspect conversions, configure tracing for your domain, then find a trace by Ray ID. Expand response and select markdown_conversion to inspect its attributes:

Attribute Meaning
cloudflare.markdown.outcome completed, completed_partial, or a conversion error code, including unfinished for streams without a terminal outcome.
cloudflare.markdown.input_bytes Decompressed HTML bytes queued for conversion, capped at the input limit.
cloudflare.markdown.output_bytes Markdown bytes emitted by the converter, not necessarily delivered to the client.
cloudflare.markdown.cpu_time_us Approximate converter CPU time, in microseconds.
cloudflare.markdown.longest_slice_us Longest converter processing slice, in microseconds.
cloudflare.markdown.input_truncated Whether a content limit truncated the HTML input.
cloudflare.markdown.frontmatter_omitted Whether a content limit omitted front matter.
cloudflare.markdown.jsonld_omitted Whether a content limit omitted JSON-LD.

Span duration includes waits for the origin body and downstream backpressure. It is not converter CPU time, and a completed conversion does not guarantee delivery to the client.

Content-limit flags are omitted for panicked or unfinished conversions because their final state is unknown. The span does not capture HTML or Markdown content.

Availability and Pricing

Markdown for Agents is available to Pro, Business and Enterprise plans, and SSL for SaaS customers at no cost.

Try it with Cloudflare

We have enabled this feature in our Developer Documentation ↗︎ and our Blog ↗︎, inviting all AI crawlers and agents to consume our content using markdown instead of HTML.

curl https://blog.cloudflare.com/markdown-for-agents/ \
  -H "Accept: text/markdown"

Limitations

  • We only convert from HTML, other types of documents may be included in the future.
  • Conversion is limited to 6 MiB (6,291,456 bytes) of decompressed HTML. The limit applies after decompression, not to the compressed response size.

Other Markdown conversion APIs

If you’re building AI systems that require arbitrary document conversion from outside Cloudflare or Markdown for Agents is not available from the content source, we provide other ways to convert documents to Markdown for your applications:

  • Workers AI AI.toMarkdown() supports multiple document types and summarization.
  • The Browser Run /markdown endpoint supports markdown conversion if you need to render a dynamic page or application in a real browser before converting it.

Was this helpful?