Built for Agents: Markdown-Native Content Negotiation, CLI Workflows, and API integration

The web was built for browsers. HTML, CSS, JavaScript, navigation bars, cookie banners, and script tags all exist to render content visually for humans. That worked for decades. But in 2026, a growing share of HTTP requests are not coming from browsers at all. They are coming from AI agents.

Tools like Claude Code, OpenCode, and Cursor now fetch web pages as part of their workflows, pulling in documentation, specs, and reference material to help developers build software. The problem is that these agents do not need the visual presentation layer. They need the content. And HTML is an expensive, noisy way to deliver it.

That reality is driving a shift across the web toward serving Markdown to agents through standard HTTP content negotiation. Cloudflare recently launched its Markdown for Agents feature, converting HTML to Markdown at the edge when agents request it. Vercel updated its blog and changelog to support the same pattern. The direction is clear: Markdown is becoming the lingua franca for agent-to-server communication.

What Is Changing: Content Negotiation via the Accept Header

HackMD already supports retrieving raw Markdown content by appending .md to the end of any note URL. For example:

https://hackmd.io/@user/note-id.md

This returns the raw Markdown source of the note. It works, and many developers and scripts already use it. But it requires the client to know about and modify the URL, which is not how modern AI agents operate.

AI agents use HTTP content negotiation. They send an Accept header with their request to tell the server what format they prefer. When an agent sends Accept: text/markdown, it is asking for Markdown if the server can provide it. This is standard HTTP behavior defined in RFC 7231 and RFC 7763 (which registered the text/markdown media type).

HackMD is implementing support for this standard. When a client sends Accept: text/markdown with a higher priority than text/html, HackMD will return the Markdown content directly instead of the rendered HTML page.

Here is what that looks like in practice:

curl https://hackmd.io/@user/note-id \
  -H "Accept: text/markdown"

The response comes back as clean Markdown:

HTTP/2 200
content-type: text/markdown; charset=utf-8
vary: Accept
# Your Note Title
The full Markdown content of the note...

How It Works Under the Hood

The implementation follows a few clear principles:

Header detection. HackMD checks the incoming request’s Accept header. If text/markdown is present and its priority (q-value) is higher than text/html, the server triggers the Markdown response path.

Logic reuse. The backend logic for returning Markdown already exists (it powers the .md URL suffix). Content negotiation reuses that same path, so there is no separate rendering pipeline to maintain.

Proper response headers. The response includes Content-Type: text/markdown; charset=utf-8 and a Vary: Accept header. The Vary header is critical because it tells CDNs and browser caches not to mix up HTML and Markdown responses for the same URL.

Token count metadata. Following the pattern established by Cloudflare, HackMD may also include an x-markdown-tokens header in the response, giving agents an estimated token count for the document. This helps agents manage context windows and decide on chunking strategies before processing the content.

Why This Matters

This is not just a developer convenience. It represents a meaningful improvement for AI-powered workflows:

AI agents can consume HackMD content directly. No HTML parsing, no stripping navigation elements, no guessing where the content starts and the chrome ends. The Markdown is the content.

Reduced bandwidth and token usage. A typical HTML page carries significant overhead from markup, scripts, and styling. Markdown delivers the same semantic content at a fraction of the size. Cloudflare has reported that Markdown can reduce token usage by up to 80% compared to HTML for equivalent content.

No URL modification required. Agents do not need to know about the .md suffix convention. They use the same URL a human would visit, and the server responds with the right format based on the Accept header. This is how HTTP was designed to work.

Read more: Choosing a CMS for Technical Teams in 2026: Git-Based vs. Headless vs. Collaborative Markdown

The HackMD CLI: A Terminal-Native Interface for Agentic Workflows

Content negotiation addresses how agents retrieve content over HTTP. But many agentic workflows do not start in a browser or with a URL fetch. They start in the terminal.

AI coding agents like Claude Code operate primarily through the command line. They run shell commands, read files, execute scripts, and interact with APIs through CLI tools. For these agents, a well-structured CLI is just as important as a well-structured HTTP response.

HackMD provides a dedicated command line tool (@hackmd/hackmd-cli) that gives both developers and agents programmatic access to notes, teams, and workspaces from the terminal. Install it globally via npm:

npm install -g @hackmd/hackmd-cli

Key Commands for Agentic Workflows

Export notes as Markdown. An agent can pull the content of any note directly into a local file or stdout:

hackmd-cli export --noteId=kNFWV5E-Qz-QP7u6XnNvyQ

This outputs the raw Markdown content, ready for the agent to process, analyze, or incorporate into a code generation workflow.

Import Markdown files as new notes. Agents can push locally generated content (meeting notes, specs, documentation drafts) straight into HackMD:

hackmd-cli import /path/to/file.md --team=my-team

The command returns the URL of the newly created note, which can then be shared or referenced in downstream workflows.

List and browse notes. Agents can query the workspace to find relevant notes:

hackmd-cli list --team=my-team --output=json

The --output=json flag is particularly important for agentic use. It returns structured data that agents can parse programmatically instead of human-formatted table output.

Browse history. Agents can retrieve recent editing history to understand what has changed:

hackmd-cli history --output=json

Why CLI Access Matters for Agents

CLI tools are the hands of an AI agent. When an agent can export a note, modify it locally, and import the updated version back into HackMD, it can participate in documentation workflows the same way a human collaborator would.

This is especially relevant for workflows like:

• Generating or updating documentation as part of a CI/CD pipeline
• Pulling specs from HackMD into a local codebase for reference during code generation
• Summarizing meeting notes and pushing the summary back into the team workspace
• Keeping local Markdown files in sync with shared HackMD notes

The CLI bridges the gap between HackMD’s collaborative editor and the terminal-first world where agents operate.

The HackMD API: Full Programmatic Access

For more complex integrations, the HackMD API provides full CRUD access to notes, teams, and user data via REST endpoints. The API uses bearer token authentication and returns JSON responses, making it straightforward for agents (and agent frameworks) to integrate with.

The Swagger documentation provides a complete interactive reference for all available endpoints.

Key capabilities include:

• Creating, reading, updating, and deleting notes programmatically
• Managing team memberships and permissions
• Uploading attachments
• Querying notes by team, tag, or user

Any workflow that an agent can describe in natural language (“create a new note in the engineering team with this content”) can be implemented as a series of API calls. And since HackMD notes are Markdown from creation to consumption, there is no format translation layer to manage.

Read more: HackMD Developer Portal — Getting Started

Markdown-Native by Design

The broader industry is scrambling to make the web work for agents. CDN providers are adding edge conversion layers. CMS platforms are building Markdown export pipelines. Static site generators are bolting on content negotiation middleware.

HackMD does not need any of that. The platform was built on Markdown from day one. Every note is authored in Markdown, stored in Markdown, versioned in Markdown, and now served to agents in Markdown through standard HTTP content negotiation.

That is not a feature. It is the architecture.

When you combine native Markdown storage with content negotiation, a CLI that agents can call from the terminal, and a REST API for deeper integrations, you get a platform that fits into agentic workflows without adaptation. No parsing layers. No format conversion. No special endpoints.

HackMD is documentation infrastructure that agents can use as naturally as humans do.

Getting Started

If you want to make your HackMD content accessible to AI agents today:

1. Use the .md suffix. Append .md to any note URL to get the raw Markdown content. This works right now.
2. Set up the CLI. Install @hackmd/hackmd-cli and use export to pull notes into your local or agent-driven workflows.
3. Generate an API token. Visit the Developer Portal to create a token and start building integrations.
4. Watch for content negotiation support. As HackMD rolls out Accept: text/markdown header support, your agents will be able to fetch content without any URL modifications.

The agents are already here. They are fetching documentation, reading specs, and pulling in context to help developers build faster. HackMD is ready for them.