# Save API — URL to Markdown

> Turn any URL into clean, LLM-ready Markdown with one HTTP call. Built for AI agents, RAG pipelines, and scrapers. The same engine behind the Save extension, as a developer API.

This page is the agent-readable spec. Human docs: https://www.minibase.md/api

## Endpoint

```
POST https://api.savemarkdown.co/v1/convert
Authorization: Bearer sk_live_...
Content-Type: application/json
```

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | The page to convert. http(s) only. |
| `template` | string | no | Omit for raw Markdown (no LLM). Pass an AI template (`clean`, `summary`, `outline`, …) to reshape the content with an LLM (token-metered). |
| `render` | `"auto"` \| `"never"` \| `"always"` | no | JavaScript rendering. Default `"auto"` escalates to a headless render only when a page is a JS shell. |
| `fresh` | boolean | no | Bypass the 24h cache and refetch. |

## Response

```json
{
  "markdown": "📄 Title: Example Article\n🔗 Source: ...\n\n---\n\n## Heading\n\nClean body...",
  "meta": { "tier": 1, "cached": false, "domain": "example.com", "template": "markdown" },
  "usage": { "credits": 1 }
}
```

`meta.tier` is `1` (fetch + extract, no LLM), `2` (headless render), or `"adapter"` (platform channel, e.g. YouTube). It tells you which rate applied.

## Examples

### curl

```bash
curl -X POST https://api.savemarkdown.co/v1/convert \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'
```

### JavaScript

```js
const res = await fetch("https://api.savemarkdown.co/v1/convert", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SAVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com/article" }),
});
const { markdown } = await res.json();
```

### Python

```python
import os, requests
res = requests.post(
    "https://api.savemarkdown.co/v1/convert",
    headers={"Authorization": f"Bearer {os.environ['SAVE_API_KEY']}"},
    json={"url": "https://example.com/article"},
)
print(res.json()["markdown"])
```

## Errors

| Status | Meaning |
| --- | --- |
| 400 | Bad request (missing/invalid `url`, blocked address) |
| 401 | Missing or invalid API key |
| 403 | API not yet enabled for live keys |
| 422 | Could not extract readable content |
| 429 | Rate limit exceeded (`Retry-After` header) |

## How it works

1. **Fetch** — server-side request with a real browser fingerprint and an SSRF guard. Static/SSR pages stop here (cheapest).
2. **Render** — if a page is a JavaScript shell, escalate to a headless render, then extract.
3. **Extract** — strip nav, ads, cookie banners and boilerplate; keep headings, lists, links, images, code.

## Pricing

| Tier | Price |
| --- | --- |
| Markdown (fetch + extract, no LLM) | $2 / 1,000 pages |
| Rendered (JavaScript pages) | $8 / 1,000 pages |
| AI-formatted (templates) | $3 / $25 per 1M input / output tokens |

Pay per call ($0.01, below) or flat plans. Pay as you go, no seats.

## Walled gardens

YouTube routes through its official transcript channel. X / Instagram / TikTok are best-effort. We never use ghost accounts or scrape behind logins.

## Access — pay per call, no account at all (x402 and MPP)

The machine door. Call the endpoint with **no credentials** and it answers `402 Payment Required` instead of `401`, quoting a price you can satisfy on the spot — no signup, no key, no human in the loop.

(A human evaluating before committing to a plan can get a free key — 30 conversions/month — from the [docs page](https://www.minibase.md/api). Paid keys: hello@minibase.md.)

```bash
curl -i -X POST https://api.minibase.md/v1/convert \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'
```

One 402 answers both protocols at once. The x402 terms come back base64-encoded in the `payment-required` header:

```json
{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "10000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xfb8157a583e3050440301f418f5e890190222a5c",
    "maxTimeoutSeconds": 300
  }]
}
```

Pay the USDC transfer on Base and repeat the request with the payment attached; the conversion returns in the same round trip.

- **Price**: $0.01 per conversion (`amount` is atomic USDC — 6 decimals)
- **Network**: Base mainnet (`eip155:8453`), USDC only
- **Protocol**: [x402](https://x402.org), `x402Version 2`, scheme `exact`
- **Settlement**: the deposit address is issued by Stripe; we hold no wallet and no private key
- **Not required**: presenting an API key skips this entirely — same quota, same plans, same `401` on a bad key

The MPP challenge comes back in the same response, in the `WWW-Authenticate` header:

```
www-authenticate: Payment id="CuHl2FqE9NlT4Iqp5-O7XL8UPSIR...", realm="api.minibase.md",
                  method="tempo", intent="charge", request="<base64>", expires="..."
```

Decoded, `request` carries:

```json
{
  "amount": "10000",
  "currency": "0x20C0000000000000000000b9537d11c60E8b50",
  "recipient": "0x248970469b7f5f980fcb4b4b5ab6a92c85719e8d",
  "methodDetails": { "chainId": 4217 }
}
```

- **Protocol**: [MPP](https://mpp.dev) (Machine Payments Protocol, authored by Stripe and Tempo)
- **Network**: Tempo mainnet (`chainId 4217`), USDC
- **Method**: `tempo` / `charge` only. The fiat half of MPP (Shared Payment Tokens) requires a US or Canada legal entity, which we are not, so it is deliberately not registered.
- **Coexistence**: x402 lives in `payment-required`, MPP in `WWW-Authenticate`. The two headers never collide, so a client reads its own and ignores the other.

## Discovery

- Agent skills: https://www.minibase.md/.well-known/agent-skills/index.json (`save.api.url-to-markdown`)
- Agent card: https://www.minibase.md/.well-known/agent-card.json
- API catalog: https://www.minibase.md/.well-known/api-catalog.json
- llms.txt: https://www.minibase.md/llms.txt
- MPP discovery (OpenAPI 3.1 + `x-payment-info`, the document MPP registries and the mpp.dev services MCP read): https://api.minibase.md/openapi.json
