API Reference

Documentation

Simple, predictable API for extracting markdown from any URL.

POST/extract

Extract markdown content from a URL

Request Body

JSON

{
  "url": "https://example.com/article"
}

url—The URL to extract content from. Must be HTTP or HTTPS.

Success Response (200)

JSON

{
  "success": true,
  "version": "1.0.0",
  "extractionPolicyVersion": "2026-02-13.v1",
  "url": "https://example.com/article",
  "canonicalUrl": "https://example.com/article",
  "title": "Article Title",
  "markdown": "# Article Title\n\nContent here...",
  "contentHash": "a1b2c3d4e5f6...",
  "extractedAt": "2025-02-13T10:00:00Z",
  "diagnostics": {
    "strictMode": true,
    "contentType": "text/html",
    "contentLength": 4523,
    "redirectCount": 0
  }
}

Response Fields

Field	Type	Description
success	boolean	Whether extraction succeeded
version	string	API version
url	string	Original requested URL
canonicalUrl	string	Canonical URL from page metadata
title	string	Page title (from <title> or <h1>)
markdown	string	Extracted content as markdown
contentHash	string	SHA-256 hash of markdown (for deduplication)
extractedAt	string	ISO 8601 timestamp
diagnostics	object	Extraction metadata

Error Codes

Code	Status	Description
`invalid_url`	400	URL is missing, malformed, or uses an unsupported protocol
`blocked_url`	400	URL points to a blocked hostname (localhost, private IP, internal domain)
`fetch_failed`	400	Failed to fetch the URL (network error or upstream HTTP error status)
`too_many_redirects`	400	Redirect chain exceeded maximum allowed redirects
`timeout`	400	Request exceeded the 30-second timeout limit
`too_large`	400	Response body exceeded the 10MB size limit
`unsupported_content_type`	400	Content-Type is not HTML, markdown, or plain text
`empty_content`	400	Response body was empty after filtering
`unauthorized`	401	Missing or invalid API key when key auth is enabled
`rate_limited`	429	Request quota exceeded for current key and window
`idempotency_conflict`	409	Idempotency key reused with a different URL
`invalid_request`	400	Request body is invalid JSON
`internal_error`	500	Unhandled server error
`unsupported_api_version`	400	Requested API version is not supported

Error Response Format

400 Bad Request

{
  "success": false,
  "code": "invalid_url",
  "message": "URL is required and must be a string",
  "requestId": "7f1c9f34-3b56-4a3a-9d65-1bb09a9fc431"
}

Limits & Guardrails

Request timeout30 seconds

Max response size10 MB

Max redirects5

Rate limit (Free)100 requests/hour

Rate limit (Paid)Based on plan

OpenAPI Specification

Download the complete machine-readable OpenAPI 3.0 specification for programmatic integration.

View OpenAPI Download JSON

Examples

cURL

bash

curl -X POST https://api.markdownforagents.com/extract \
  -H "x-api-key: YOUR_KEY" \
  -H "Idempotency-Key: req-123" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'

JavaScript

javascript

const response = await fetch('https://api.markdownforagents.com/extract', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_KEY',
    'Idempotency-Key': 'req-123'
  },
  body: JSON.stringify({ url: 'https://example.com/article' })
});

const data = await response.json();
if (data.success) {
  console.log(data.markdown);
  console.log('Content hash:', data.contentHash);
}

Try it yourself

Test the API with our interactive demo.

Open Demo