# AgentMD

> Document-to-markdown conversion API built for AI agents. Send a PDF, DOCX, HTML file, or any URL; get back clean, LLM-ready markdown with tables preserved and navigation/boilerplate stripped. Available as a REST API and as an MCP server. 50 free conversions per email (self-serve, no card), then $0.002 per successful conversion with no per-seat licensing.

AgentMD exists because agents ingest documents constantly and most document formats are hostile to language models. It is deliberately headless: there is no dashboard to click through, and every capability is reachable programmatically.

## Quick start

REST (convert a URL):

```
curl -X POST https://www.getagentmd.com/api/v1/convert \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'
```

REST (upload a file): POST multipart/form-data with a `file` field, or JSON with `base64` and `filename`.

MCP (streamable HTTP): `https://www.getagentmd.com/api/mcp` with header `Authorization: Bearer <key>`.

MCP (stdio, one-line install): `npx agentmd-mcp`, with `AGENTMD_API_KEY` in the environment.

## Reading only part of a document

Four optional parameters (JSON body, multipart fields, or MCP tool arguments) keep large documents out of your context: `pages` for 1-indexed PDF page ranges like `"1-3,5,8-"`, `mode: "outline"` for just the heading tree, `section` for one section by `"#3"` or heading text, and `maxTokens` to cap the output at a paragraph boundary. They apply in that order. For anything long, call with `mode: "outline"` first, then re-request with `section` set to the index you want — `meta.totalApproxTokens` and `meta.truncated` tell you how much was left out.

## Response shape

```json
{
  "markdown": "...",
  "meta": {
    "sourceFormat": "pdf",
    "pages": 12,
    "title": "Quarterly Report",
    "characters": 48210,
    "approxTokens": 12053,
    "truncated": false,
    "totalApproxTokens": 12053,
    "durationMs": 640
  },
  "warnings": []
}
```

## Supported inputs

- PDF — text extraction; scanned/image-only PDFs return a warning (OCR not yet supported)
- DOCX — headings, lists, and tables preserved
- HTML and URLs — main-article extraction, GFM tables, links resolved to absolute URLs
- Markdown and plain text — normalized passthrough
- Limit: 25 MB per document; URL fetches time out after 30 seconds

## Getting an API key

Free tier (no card, fully programmatic — agents can do this themselves):

```
curl -X POST https://www.getagentmd.com/api/v1/keys/free \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'
```

Returns `{ "api_key": "amd_free_...", "quota": 50 }`. The key is shown only once and includes 50 free conversions (one free key per email). When the quota is exhausted, requests return HTTP 402 with an upgrade link.

Pay-per-call: sign up via Stripe Checkout at https://www.getagentmd.com/api/checkout ($0.002 per successful conversion, billed monthly). Requests without a valid key receive HTTP 401.

## Docs

- Landing page and examples: https://www.getagentmd.com
- OpenAPI specification: https://www.getagentmd.com/openapi.json